Grails

GroovyDoc for GSP tags

Details

  • Type: New Feature New Feature
  • Status: Closed Closed
  • Priority: Major Major
  • Resolution: Fixed
  • Affects Version/s: None
  • Fix Version/s: 1.3.6, 1.4-M1
  • Component/s: TagLib
  • Labels:
    None

Description

In order to help IDE processing of GSP tags, it would be helpful to have specially formatted GroovyDoc, so that a tag description and potential attributes are properly described. Here is a suggestion:

/**
 * This is a description of the tag.  It 
 * will appear when selecting the tag in
 * hovers, content assist, etc.
 *
 * @attr myAttr This is an optional attribute 
 * and this description will appear in hovers,
 * etc.
 * 
 * @attr myAttr2 REQUIRED This is a required attribute
 * It will appear by default when this tag is selected
 * in content assist. ("REQUIRED" can be case-insensitive)
 */
def myTag = { }

From Grails' point of view, we just need to standardize a recommended format for GroovyDoc on tags. Then IDEs can parse the GroovyDoc and provide the proper support.

From my point of view, the above contains all the information I need, but I am open to other suggestions on what format the doc should take.

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Andrew Eisenberg added a comment -

And I forgot to mention that this kind of GroovyDoc would be optional. If it's not there, STS will still do a best effort guess at what the attrs are. Also, if descriptions are missing (ie- just tag names and nothing else), then that wouldn't be a problem either.

Show
Andrew Eisenberg added a comment - And I forgot to mention that this kind of GroovyDoc would be optional. If it's not there, STS will still do a best effort guess at what the attrs are. Also, if descriptions are missing (ie- just tag names and nothing else), then that wouldn't be a problem either.
Hide
Permalink
Burt Beckwith added a comment -

Should also update doc generator to use the new information.

Show
Burt Beckwith added a comment - Should also update doc generator to use the new information.
Hide
Permalink
Andrew Eisenberg added a comment -

I raised https://issuetracker.springsource.com/browse/STS-1350 to track the IDE side of this. The IDE will be able to handle some HTML tags in the formatting, such as ol, ul, li, b, etc. Unsupported tags such as a will just be removed. JavaDoc tags such as @see and @link will likely be ignored, but I can probably do something with them if desired.

Show
Andrew Eisenberg added a comment - I raised https://issuetracker.springsource.com/browse/STS-1350 to track the IDE side of this. The IDE will be able to handle some HTML tags in the formatting, such as ol, ul, li, b, etc. Unsupported tags such as a will just be removed. JavaDoc tags such as @see and @link will likely be ignored, but I can probably do something with them if desired.
Hide
Permalink
Andrew Eisenberg added a comment -

How will this handle the builtin GSP tags like 'if' and 'set', etc?

Show
Andrew Eisenberg added a comment - How will this handle the builtin GSP tags like 'if' and 'set', etc?
Hide
Permalink
Andrew Eisenberg added a comment -

The work on the STS side is mostly complete. I just need to test it out on some real-world examples. Please let me know when you have a build of Grails that I can try this against.

Show
Andrew Eisenberg added a comment - The work on the STS side is mostly complete. I just need to test it out on some real-world examples. Please let me know when you have a build of Grails that I can try this against.
Hide
Permalink
Andrew Eisenberg added a comment -

Any update on the progress here? It would be great if this could make it into the next upcoming release of Grails and STS. Or, at least updating the documentation for the more important plugins.

Show
Andrew Eisenberg added a comment - Any update on the progress here? It would be great if this could make it into the next upcoming release of Grails and STS. Or, at least updating the documentation for the more important plugins.
Hide
Permalink
Andrew Eisenberg added a comment -

Thanks. I'm guessing that I can try this out in a dev build of 1.3.6?

Show
Andrew Eisenberg added a comment - Thanks. I'm guessing that I can try this out in a dev build of 1.3.6?
Hide
Permalink
Burt Beckwith added a comment -

We had a few failing builds but that's fixed, so grab any 1.3.6 build at http://hudson.grails.org/job/grails_core_1.3.x/ #43 or higher. You can also test in a recent 1.4 build at http://hudson.grails.org/job/grails_core_1.4.x/ #428 or higher.

Show
Burt Beckwith added a comment - We had a few failing builds but that's fixed, so grab any 1.3.6 build at http://hudson.grails.org/job/grails_core_1.3.x/ #43 or higher. You can also test in a recent 1.4 build at http://hudson.grails.org/job/grails_core_1.4.x/ #428 or higher.
Hide
Permalink
Andrew Eisenberg added a comment -

Thanks. I checked a few things out and this looks good. I now need to make a few changes in STS, but this enhance JavaDoc support will make it into STS 2.5.2.

Show
Andrew Eisenberg added a comment - Thanks. I checked a few things out and this looks good. I now need to make a few changes in STS, but this enhance JavaDoc support will make it into STS 2.5.2.
Hide
Permalink
Andrew Eisenberg added a comment -

One thing I notice is that you are not using HTML formatting in your doc tags and this is making some of them a bit difficult to read. For example, the doc for FormTagLib.actionSubmit is written like this:

    /**
     * Creates a an image submit button that submits to an action in the controller specified by the form action
     * The name of the action attribute is translated into the action name, for example "Edit" becomes
     * "_action_edit" or "List People" becomes "_action_listPeople"
     * If the action attribute is not specified, the value attribute will be used as part of the action name
     *
     * <g:actionSubmitImage src="/images/submitButton.gif" action="Edit" />
     *
     * @attr value REQUIRED The title of the button and name of action when not explicitly defined.
     * @attr action The name of the action to be executed, otherwise it is derived from the value.
     * @attr src The source of the image to use
     */

but is displayed like this:

Creates a submit button that submits to an action in the controller specified by the form action The name 
 of the action attribute is translated into the action name, for example "Edit" becomes "_action_edit" or 
 "List People" becomes "_action_listPeople" If the action attribute is not specified, the value attribute will 
 be used as part of the action name

If you were instead to use some HTML tags in there, things would render quite a bit nicer, especially for the embedded GSP snippet:

    /**
     * Creates a an image submit button that submits to an action in the controller specified by the form action
     * The name of the action attribute is translated into the action name, for example <em>Edit</em> becomes
     * "_action_edit" or "List People" becomes "_action_listPeople"
     * If the action attribute is not specified, the value attribute will be used as part of the action name
     * <br/><br/>
     * <pre><g:actionSubmitImage src="/images/submitButton.gif" action="Edit" /></pre>
     *
     * @attr value REQUIRED The title of the button and name of action when not explicitly defined.
     * @attr action The name of the action to be executed, otherwise it is derived from the value.
     * @attr src The source of the image to use
     */

Shall I raise a new bug for this?

Show
Andrew Eisenberg added a comment - One thing I notice is that you are not using HTML formatting in your doc tags and this is making some of them a bit difficult to read. For example, the doc for FormTagLib.actionSubmit is written like this: /** * Creates a an image submit button that submits to an action in the controller specified by the form action * The name of the action attribute is translated into the action name, for example "Edit" becomes * "_action_edit" or "List People" becomes "_action_listPeople" * If the action attribute is not specified, the value attribute will be used as part of the action name * * <g:actionSubmitImage src= "/images/submitButton.gif" action= "Edit" /> * * @attr value REQUIRED The title of the button and name of action when not explicitly defined. * @attr action The name of the action to be executed, otherwise it is derived from the value. * @attr src The source of the image to use */ but is displayed like this: Creates a submit button that submits to an action in the controller specified by the form action The name of the action attribute is translated into the action name, for example "Edit" becomes "_action_edit" or "List People" becomes "_action_listPeople" If the action attribute is not specified, the value attribute will be used as part of the action name If you were instead to use some HTML tags in there, things would render quite a bit nicer, especially for the embedded GSP snippet: /** * Creates a an image submit button that submits to an action in the controller specified by the form action * The name of the action attribute is translated into the action name, for example <em>Edit</em> becomes * "_action_edit" or "List People" becomes "_action_listPeople" * If the action attribute is not specified, the value attribute will be used as part of the action name * <br/><br/> * <pre><g:actionSubmitImage src= "/images/submitButton.gif" action= "Edit" /></pre> * * @attr value REQUIRED The title of the button and name of action when not explicitly defined. * @attr action The name of the action to be executed, otherwise it is derived from the value. * @attr src The source of the image to use */ Shall I raise a new bug for this?
Hide
Permalink
Andrew Eisenberg added a comment -

Hmmm...I can't edit my comments here. This:

<pre><g:actionSubmitImage src="/images/submitButton.gif" action="Edit" /></pre>

Should be replaced with something like this using proper HTML escape sequences:

<pre>&lt;g:actionSubmitImage src="/images/submitButton.gif" action="Edit" /&gt;</pre>
Show
Andrew Eisenberg added a comment - Hmmm...I can't edit my comments here. This: <pre><g:actionSubmitImage src= "/images/submitButton.gif" action= "Edit" /></pre> Should be replaced with something like this using proper HTML escape sequences: <pre>&lt;g:actionSubmitImage src= "/images/submitButton.gif" action= "Edit" /&gt;</pre>
Hide
Permalink
Burt Beckwith added a comment -

I noticed that and fixed a few but there are several more to do. I'll update those before the 1.3.6 release, no need for another issue.

Show
Burt Beckwith added a comment - I noticed that and fixed a few but there are several more to do. I'll update those before the 1.3.6 release, no need for another issue.

People

  • Assignee:
    Burt Beckwith
    Reporter:
    Andrew Eisenberg
Vote (2)
Watch (2)

Dates

  • Created:
    Updated:
    Resolved: