Pages: 1
  Print  
Author Topic: Code Action Comments  (Read 6327 times)
Offline (Male) Goombert
Posted on: December 07, 2014, 06:41:41 pm

Developer
Location: Cappuccino, CA
Joined: Jan 2013
Posts: 2993

View Profile
This has been in Studio for a while, you can use /// on the first line of code action to change its descriptive label. I just want to know what everyone thinks of this feature, maybe we could add it to LGM or not, would just like to know what people think.


From the GMC:
http://gmc.yoyogames.com/index.php?s=2dbd49a45df4db76813855b67a017983&showtopic=646815
Logged
I think it was Leonardo da Vinci who once said something along the lines of "If you build the robots, they will make games." or something to that effect.

Offline (Male) Rusky
Reply #1 Posted on: December 07, 2014, 10:10:03 pm

Resident Troll
Joined: Feb 2008
Posts: 954
MSN Messenger - rpjohnst@gmail.com
View Profile WWW Email
It's the next best thing to directly viewing the code in the object editor.
Logged
Offline (Male) Goombert
Reply #2 Posted on: December 07, 2014, 10:16:11 pm

Developer
Location: Cappuccino, CA
Joined: Jan 2013
Posts: 2993

View Profile
I can't decide if I like it or not, it just seems like this may not play well with doxygen comments if say the user uses doxygen copyright headers.
Logged
I think it was Leonardo da Vinci who once said something along the lines of "If you build the robots, they will make games." or something to that effect.

Offline (Male) Josh @ Dreamland
Reply #3 Posted on: December 08, 2014, 12:25:57 am

Prince of all Goldfish
Developer
Location: Pittsburgh, PA, USA
Joined: Feb 2008
Posts: 2950

View Profile Email
It's a cheap hack compared to actually allowing you to name it in a field, which I'd recommend doing since EGM and GMX are extensible. Why Dailly didn't do that, I'll never know.
Logged
"That is the single most cryptic piece of code I have ever seen." -Master PobbleWobble
"I disapprove of what you say, but I will defend to the death your right to say it." -Evelyn Beatrice Hall, Friends of Voltaire
Offline (Male) Goombert
Reply #4 Posted on: December 08, 2014, 12:37:51 am

Developer
Location: Cappuccino, CA
Joined: Jan 2013
Posts: 2993

View Profile
Josh, how could we parse the comments to look for an @description field?
Logged
I think it was Leonardo da Vinci who once said something along the lines of "If you build the robots, they will make games." or something to that effect.

Offline (Unknown gender) TheExDeus
Reply #5 Posted on: December 08, 2014, 06:02:51 am

Developer
Joined: Apr 2008
Posts: 1860

View Profile
We could do both. Have a /// syntax for compatibility and ease of use, as well as have some kind of @description tag (maybe more pretty) which would override the /// comment. So it would work with doxygen.
Logged
Offline (Male) Josh @ Dreamland
Reply #6 Posted on: December 13, 2014, 11:41:22 am

Prince of all Goldfish
Developer
Location: Pittsburgh, PA, USA
Joined: Feb 2008
Posts: 2950

View Profile Email
The question isn't about a tag so much as an actual GUI field—Something users would be able to find without looking for it. But whatever.

Any of ///, //!, /** */, or /*! */ are perfectly valid ways of specifying a formal comment. JoshEdit supports highlighting them correctly. By default, the first sentence (up to the first period or pair of newlines) is used as the brief. Otherwise, the tag is @brief, or \brief in vanilla Doxygen. The explicit tags extend the brief to as many sentences as you like; it ends at the first pair of newlines (or end of the comment).

JoshEdit already knows where block boundaries are (strings, comments, etc), so you can either ask it, or just recompute them yourself (which is pretty simple).


To clarify:
Code: (edl) [Select]
/// This is a function that
/// does some stuff. This
/// text elaborates on it.
The brief of the above is "This is a function that does some stuff."

Code: (edl) [Select]
/*!
 * This is a function that does some stuff and
 * was written by someone who just has no
 * concept of what a period is
 *
 * This text elaborates on it
 */
The brief of the above is "This is a function that does some stuff and was written by someone who just has no concept of what a period is." Note that the behavior is not affected at all by the existence of asterisks.

Code: (edl) [Select]
/**
 * @brief This is a function that does some
 *     stuff. Really well, actually. (Thanks for asking.)
 *
 * This text elaborates on it.
 */
The brief of the above is the entire paragraph, "This is a function that does some stuff. Really well, actually. (Thanks for asking.)."

Code: (edl) [Select]
/// \brief This is a function that
/// does some stuff. It's also pretty
/// serious with Doxygen.
/// \param foo  the first parameter
The brief of the above is "This is a function that does some stuff. It's also pretty serious with Doxygen."


As long as I'm repeatedly adding information to this post, I'll point out one more thing: Normally a Doxygen comment precedes a function or variable. If we are REALLY shooting for Doxygen compliance, the "correct" way to do this terrible hack is to leverage the @file tag, or create a new @action tag.

This is the only way to denote to Doxygen that a comment applies to the file, not to a function or other object.
« Last Edit: December 13, 2014, 11:54:34 am by Josh @ Dreamland » Logged
"That is the single most cryptic piece of code I have ever seen." -Master PobbleWobble
"I disapprove of what you say, but I will defend to the death your right to say it." -Evelyn Beatrice Hall, Friends of Voltaire
Offline (Unknown gender) Mangolion
Reply #7 Posted on: December 16, 2014, 12:19:01 am
Member
Joined: Sep 2014
Posts: 19

View Profile Email
Why don't we implement JavaDoc then?
Logged
Pages: 1
  Print