groovy
  1. groovy
  2. GROOVY-5027

Groovydoc calculateFirstSentence doesn't recognise html tags as breaks

    Details

    • Type: Bug Bug
    • Status: Closed 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
    • Patch Submitted:
      Yes
    • Number of attachments :
      1

      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

        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
        Guillaume Laforge made changes -
        Field Original Value New Value
        Assignee Guillaume Laforge [ guillaume ]
        Hide
        Guillaume Laforge added a comment -

        Thank you Tim!

        Show
        Guillaume Laforge added a comment - Thank you Tim!
        Guillaume Laforge made changes -
        Status Open [ 1 ] Resolved [ 5 ]
        Fix Version/s 1.8.3 [ 17657 ]
        Fix Version/s 1.9-beta-4 [ 17656 ]
        Resolution Fixed [ 1 ]
        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.
        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 -

        ok, tweaks are committed

        Show
        Paul King added a comment - ok, tweaks are committed
        Paul King made changes -
        Status Resolved [ 5 ] Closed [ 6 ]

          People

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

            Dates

            • Created:
              Updated:
              Resolved: