Code Action Comments

[Goombert]

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

[Rusky]

It's the next best thing to directly viewing the code in the object editor.

[Goombert]

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.

[Josh @ Dreamland]

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.

[Goombert]

Josh, how could we parse the comments to look for an @description field?

[TheExDeus]

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.

[Josh @ Dreamland]

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 parameterThe 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.

[Mangolion]

Why don't we implement JavaDoc then?