New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature: Add script name display in editor #233

Closed
Kayomn opened this Issue Jan 7, 2016 · 8 comments

Comments

Projects
None yet
4 participants
@Kayomn

Kayomn commented Jan 7, 2016

So in Enigma's counterpart, Game Maker, you are able to see the name of your scripts within the object you're working on. Coming from past experience from Game Maker it seems really inconvenient for all of your scripts to be named the stock value.

Surely it couldn't be that hard to make the name of the entry in the list change to the first line of the file's "///...".

Thanks in advance.

@JoshDreamland

This comment has been minimized.

Show comment
Hide comment
@JoshDreamland

JoshDreamland Jan 19, 2016

I believe it would be wise to support all four formal comment notations. At very least, I'd support these two:

/// Formal comment naming the file
//! Formal comment naming the file

It's probably wise to support these two, as well, on a first-line basis:

/**
 * Name of the file
 * Possibly other junk here
 */
/*!
 * Name of the file
 * Possibly other junk here
 */

My main objection to this is that formal comments are so called because the contents of them follow a specific grammar. The most popular of these is Doxygen. In a perfect world, the above would be acceptable, but could be overridden by @brief / \brief, or maybe @file / \file.

By specification of Doxygen, the brief of a function is the first sentence of its description (stopping at the period), unless the \brief tag is present, in which case, it's the block of text following that until the first pair of newlines. So, consider this snippet:

/*!
 * Does some stuff. In an inefficient and horrific fashion.
 */
void foo();

/**
 * @brief Does some stuff. In an inefficient
 * and horrific fashion.
 *
 * Also makes sandwiches.
 */
void bar();

So according to Doxygen, the brief for foo() is "Does some stuff." The brief for bar() is "Does some stuff. In an inefficient and horrific fashion."

That said, there's really no precedent for documenting the contents of a script. Doxygen was designed for languages with larger compilation units, so @file is used to document an entire file. But we're not dealing with files, here. Since @brief cannot apply to functions, as nested functions aren't supported in GM/ENIGMA, it might make sense to use it. But the situation is a bit weird, looking through the lens of Doxygen's intended use.

All that said, I don't know if, for instance, a JavaDoc parser would be available cheaply to LGM, but if it were, this could be a quick way of supporting Doxygen tags. For all I know, a Doxygen parser is really cheap (though I highly doubt it). Otherwise, given the lack of precedent for this sort of thing, the first-line approach sounds reasonable to me. I'd support all four of those comment specs.

JoshDreamland commented Jan 19, 2016

I believe it would be wise to support all four formal comment notations. At very least, I'd support these two:

/// Formal comment naming the file
//! Formal comment naming the file

It's probably wise to support these two, as well, on a first-line basis:

/**
 * Name of the file
 * Possibly other junk here
 */
/*!
 * Name of the file
 * Possibly other junk here
 */

My main objection to this is that formal comments are so called because the contents of them follow a specific grammar. The most popular of these is Doxygen. In a perfect world, the above would be acceptable, but could be overridden by @brief / \brief, or maybe @file / \file.

By specification of Doxygen, the brief of a function is the first sentence of its description (stopping at the period), unless the \brief tag is present, in which case, it's the block of text following that until the first pair of newlines. So, consider this snippet:

/*!
 * Does some stuff. In an inefficient and horrific fashion.
 */
void foo();

/**
 * @brief Does some stuff. In an inefficient
 * and horrific fashion.
 *
 * Also makes sandwiches.
 */
void bar();

So according to Doxygen, the brief for foo() is "Does some stuff." The brief for bar() is "Does some stuff. In an inefficient and horrific fashion."

That said, there's really no precedent for documenting the contents of a script. Doxygen was designed for languages with larger compilation units, so @file is used to document an entire file. But we're not dealing with files, here. Since @brief cannot apply to functions, as nested functions aren't supported in GM/ENIGMA, it might make sense to use it. But the situation is a bit weird, looking through the lens of Doxygen's intended use.

All that said, I don't know if, for instance, a JavaDoc parser would be available cheaply to LGM, but if it were, this could be a quick way of supporting Doxygen tags. For all I know, a Doxygen parser is really cheap (though I highly doubt it). Otherwise, given the lack of precedent for this sort of thing, the first-line approach sounds reasonable to me. I'd support all four of those comment specs.

@RobertBColton

This comment has been minimized.

Show comment
Hide comment
@RobertBColton

RobertBColton Jan 29, 2016

Collaborator

While I would also prefer something more elaborate as @JoshDreamland describes, I've now noticed it was in GM8.1 by Overmars. I think for now simply '///' will suffice.

A difference to note is that GM8.1 and the latest GMS will do the following:

Code/Comment Caption
"///test" "Test"
"/// test" "Test"
" ///test" "Execute a piece of code"
"keyboard_check(vk_space); ///test" "Execute a piece of code"

I propose this for LGM:

Code/Comment Caption
"///test" "Test"
"/// test" "Test"
" ///test" "Test"
"keyboard_check(vk_space); ///test" "Execute a piece of code"

Thoughts @JoshDreamland or @rpjohnst ?

Collaborator

RobertBColton commented Jan 29, 2016

While I would also prefer something more elaborate as @JoshDreamland describes, I've now noticed it was in GM8.1 by Overmars. I think for now simply '///' will suffice.

A difference to note is that GM8.1 and the latest GMS will do the following:

Code/Comment Caption
"///test" "Test"
"/// test" "Test"
" ///test" "Execute a piece of code"
"keyboard_check(vk_space); ///test" "Execute a piece of code"

I propose this for LGM:

Code/Comment Caption
"///test" "Test"
"/// test" "Test"
" ///test" "Test"
"keyboard_check(vk_space); ///test" "Execute a piece of code"

Thoughts @JoshDreamland or @rpjohnst ?

@rpjohnst

This comment has been minimized.

Show comment
Hide comment
@rpjohnst

rpjohnst Jan 29, 2016

Contributor

There is precedent for doc comments being inside a function- Doxygen supports this (see references to "in body" descriptions here: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#cppblock), Python docstrings always go inside their function, CapnProto doc comments are automatically parsed only inside their associated declarations, etc.

However, I think supporting anything like Doxygen in LateralGM would be like using a nuke to kill a fly. All we need is to read two or three comment styles from the first line(s) of a script to extract a name, and honestly all we really need is the one triple-slash format GM:S uses.

Contributor

rpjohnst commented Jan 29, 2016

There is precedent for doc comments being inside a function- Doxygen supports this (see references to "in body" descriptions here: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#cppblock), Python docstrings always go inside their function, CapnProto doc comments are automatically parsed only inside their associated declarations, etc.

However, I think supporting anything like Doxygen in LateralGM would be like using a nuke to kill a fly. All we need is to read two or three comment styles from the first line(s) of a script to extract a name, and honestly all we really need is the one triple-slash format GM:S uses.

@JoshDreamland

This comment has been minimized.

Show comment
Hide comment
@JoshDreamland

JoshDreamland Jan 29, 2016

I prefer to think of it as nuking the fly planet. But anyway, agreed—I specifically said this isn't worth the effort (or additional bytes) if a JavaDoc parser is not readily available as part of the Java runtime. This would not surprise me, given that the HTML renderer for it is. So my question is, is com.sun.javadoc.* available by default? Or is something similar from the modern era? If so, I think it makes more sense for a project operating out of a nuke factory to bomb a fly than to order a flyswatter, even given Prime shipping.

JoshDreamland commented Jan 29, 2016

I prefer to think of it as nuking the fly planet. But anyway, agreed—I specifically said this isn't worth the effort (or additional bytes) if a JavaDoc parser is not readily available as part of the Java runtime. This would not surprise me, given that the HTML renderer for it is. So my question is, is com.sun.javadoc.* available by default? Or is something similar from the modern era? If so, I think it makes more sense for a project operating out of a nuke factory to bomb a fly than to order a flyswatter, even given Prime shipping.

@RobertBColton

This comment has been minimized.

Show comment
Hide comment
@RobertBColton

RobertBColton Jan 29, 2016

Collaborator

@rpjohnst and @JoshDreamland I am now really just asking about how to handle the white space around the comment as described in the table above.

Collaborator

RobertBColton commented Jan 29, 2016

@rpjohnst and @JoshDreamland I am now really just asking about how to handle the white space around the comment as described in the table above.

@JoshDreamland

This comment has been minimized.

Show comment
Hide comment
@JoshDreamland

JoshDreamland Jan 29, 2016

Your proposal is fine with me.

JoshDreamland commented Jan 29, 2016

Your proposal is fine with me.

@RobertBColton

This comment has been minimized.

Show comment
Hide comment
@RobertBColton

RobertBColton Jan 29, 2016

Collaborator

My first attempt at this was https://github.com/RobertBColton/LateralGM/commit/2a7f19e20e6954aa6b48cf0537477cdba3b22965 and then revised in https://github.com/RobertBColton/LateralGM/commit/d95d9e60724836d3b538c2a1cc6447a182f7b7f9 for the master branch. Josh thought that was ridiculous so I redid it in https://github.com/RobertBColton/LateralGM/commit/dd19c9f26a3ee97d9d58b72b0aa79924fb4bc52a using a regular expression he helped me create. This regex version allows it to be on the second line as long as the first line is blank.

I tested with some GameMaker games, and the LAN multiplayer example from Studio in the screenshot below. It also removes leading whitespace before the first nonwhitespace character after the comment symbol like the GM version.
Code Action Captions

Here is a table of the results:

Code/Comment Caption
"///test" "test"
"/// test" "test"
" ///test" "test"
" /// test //// test /// test // test / test" "test //// test /// test // test / test"
"//!/!//!/ comment" "comment"
"/ //test" "Execute a piece of code"
"keyboard_check(vk_space); ///test" "Execute a piece of code"
StringBuilder sb = null;
// let the user supply their own description using
// a special comment like in GM8.1 and GMS
if (a.getLibAction().actionKind == Action.ACT_CODE)
    {
    Pattern r = Pattern.compile("^\\s*//[/!]+\\s*(.+)([\r\n]|$)"); //$NON-NLS-1$
    Matcher m = r.matcher(a.getArguments().get(0).getVal());
    if (m.find())
        {
        sb = new StringBuilder(m.group(1));
        }
    }

if (sb == null)
    {
    sb = new StringBuilder("<html>"); //$NON-NLS-1$
    if (la.listText.contains("@FI")) //$NON-NLS-1$
        sb.append("<i>"); //$NON-NLS-1$
    if (la.listText.contains("@FB")) //$NON-NLS-1$
        sb.append("<b>"); //$NON-NLS-1$
    sb.append(escape(parse(la.listText,a)));
    }
actlabel.setText(sb.toString());
actlabel.setIcon(new ImageIcon(la.actImage));
Collaborator

RobertBColton commented Jan 29, 2016

My first attempt at this was https://github.com/RobertBColton/LateralGM/commit/2a7f19e20e6954aa6b48cf0537477cdba3b22965 and then revised in https://github.com/RobertBColton/LateralGM/commit/d95d9e60724836d3b538c2a1cc6447a182f7b7f9 for the master branch. Josh thought that was ridiculous so I redid it in https://github.com/RobertBColton/LateralGM/commit/dd19c9f26a3ee97d9d58b72b0aa79924fb4bc52a using a regular expression he helped me create. This regex version allows it to be on the second line as long as the first line is blank.

I tested with some GameMaker games, and the LAN multiplayer example from Studio in the screenshot below. It also removes leading whitespace before the first nonwhitespace character after the comment symbol like the GM version.
Code Action Captions

Here is a table of the results:

Code/Comment Caption
"///test" "test"
"/// test" "test"
" ///test" "test"
" /// test //// test /// test // test / test" "test //// test /// test // test / test"
"//!/!//!/ comment" "comment"
"/ //test" "Execute a piece of code"
"keyboard_check(vk_space); ///test" "Execute a piece of code"
StringBuilder sb = null;
// let the user supply their own description using
// a special comment like in GM8.1 and GMS
if (a.getLibAction().actionKind == Action.ACT_CODE)
    {
    Pattern r = Pattern.compile("^\\s*//[/!]+\\s*(.+)([\r\n]|$)"); //$NON-NLS-1$
    Matcher m = r.matcher(a.getArguments().get(0).getVal());
    if (m.find())
        {
        sb = new StringBuilder(m.group(1));
        }
    }

if (sb == null)
    {
    sb = new StringBuilder("<html>"); //$NON-NLS-1$
    if (la.listText.contains("@FI")) //$NON-NLS-1$
        sb.append("<i>"); //$NON-NLS-1$
    if (la.listText.contains("@FB")) //$NON-NLS-1$
        sb.append("<b>"); //$NON-NLS-1$
    sb.append(escape(parse(la.listText,a)));
    }
actlabel.setText(sb.toString());
actlabel.setIcon(new ImageIcon(la.actImage));
@RobertBColton

This comment has been minimized.

Show comment
Hide comment
@RobertBColton

RobertBColton Feb 5, 2016

Collaborator

Feature implemented in master, will be available in the next release.

Collaborator

RobertBColton commented Feb 5, 2016

Feature implemented in master, will be available in the next release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment