Groovy
  1. Groovy
  2. GROOVY-5027

Groovydoc calculateFirstSentence doesn't recognise html tags as breaks

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Trivial Trivial
    • Resolution: Fixed
    • Affects Version/s: 1.8.2, 1.9-beta-3
    • Fix Version/s: 1.8.3, 1.9-beta-4
    • Component/s: GroovyDoc
    • Labels:
      None
    • Flags:
      Patch

      Description

      The Method summary block of the groovydoc pages contains a sentence describing the method.

      However, if the javadoc looks like (taken from StreamingJsonBuilder.groovy):

          /**
           * Varargs elements as arguments to the JSON builder create a root JSON array
           * <p>
           * Example:
           * <pre class="groovyTestCase">
           * new StringWriter().with { w ->
           *   def json = new groovy.json.StreamingJsonBuilder( w )
           *   def result = json 1, 2, 3
           *
           *   assert result instanceof List
           *   assert w.toString() == "[1,2,3]"
           * }
           * </pre>
           * @param args an array of values
           * @return a list of values
           */
      

      Then the summary text becomes:

      Varargs elements as arguments to the JSON builder create a root JSON array
      
      Example:
      
       new StringWriter().with { w ->
         def json = new groovy.json.StreamingJsonBuilder( w )
         def result = json 1, 2, 3
      

      In this case, it is only confusing (as the assert is missed off the end, but in other cases, it could result in invalid code being shown in the summary.

      The attached patch adds another replaceAll to the calculateFirstSentence method of SimpleGroovyDoc.java which trims the javadoc as soon as an HTML tag is encountered as the first thing on a new line in the javadoc.

      The summary text for this same method then becomes simply:

      Varargs elements as arguments to the JSON builder create a root JSON array
      

        Activity

        Transition Time In Source Status Execution Times Last Executer Last Execution Date
        Open Open Resolved Resolved
        6d 5h 30m 1 Guillaume Delcroix 22/Sep/11 11:00
        Resolved Resolved Closed Closed
        21d 14h 27m 1 Paul King 14/Oct/11 01:28
        Mark Thomas made changes -
        Workflow jira [ 12971487 ] Default workflow, editable Closed status [ 12979265 ]
        Mark Thomas made changes -
        Project Import Mon Apr 06 02:11:23 UTC 2015 [ 1428286283443 ]
        Mark Thomas made changes -
        Patch Submitted Yes [ 10763 ]
        Flags Patch [ 10430 ]
        Mark Thomas made changes -
        Workflow jira [ 12733952 ] Default workflow, editable Closed status [ 12745759 ]
        Mark Thomas made changes -
        Project Import Sun Apr 05 13:32:57 UTC 2015 [ 1428240777691 ]
        Paul King made changes -
        Status Resolved [ 5 ] Closed [ 6 ]
        Hide
        Paul King added a comment -

        ok, tweaks are committed

        Show
        Paul King added a comment - ok, tweaks are committed
        Hide
        Paul King added a comment - - edited

        Hmm, seems like <p> is recognized whether it is on a newline or not but neither <p/> nor <p /> are recognized.

        Show
        Paul King added a comment - - edited Hmm, seems like <p> is recognized whether it is on a newline or not but neither <p/> nor <p /> are recognized.
        Hide
        Paul King added a comment -

        Actually, I just had a look at what javadoc (at least under jdk6 and jdk7) does. It seems like it recognises <p> as a line break but not the other tags. I suspect we want to follow javadocs lead here. I will see if I can tweak the patch accordingly.

        Show
        Paul King added a comment - Actually, I just had a look at what javadoc (at least under jdk6 and jdk7) does. It seems like it recognises <p> as a line break but not the other tags. I suspect we want to follow javadocs lead here. I will see if I can tweak the patch accordingly.
        Guillaume Delcroix made changes -
        Fix Version/s 1.8.3 [ 17657 ]
        Fix Version/s 1.9-beta-4 [ 17656 ]
        Resolution Fixed [ 1 ]
        Status Open [ 1 ] Resolved [ 5 ]
        Hide
        Guillaume Delcroix added a comment -

        Thank you Tim!

        Show
        Guillaume Delcroix added a comment - Thank you Tim!
        Guillaume Delcroix made changes -
        Field Original Value New Value
        Assignee Guillaume Laforge [ guillaume ]
        Hide
        Tim Yates added a comment -
        Show
        Tim Yates added a comment - Forgot the link to to an example gapi page http://groovy.codehaus.org/gapi/groovy/json/StreamingJsonBuilder.html
        Tim Yates created issue -

          People

          • Assignee:
            Guillaume Delcroix
            Reporter:
            Tim Yates
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development