Details

    • Type: New Feature New Feature
    • Status: 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

        Hide
        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
        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
        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
        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
        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
          • Votes:
            2 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development