groovy
  1. groovy
  2. GROOVY-4136

gapi document generation ignores access modifiers set on groovydoc

    Details

    • Type: Improvement Improvement
    • Status: Open Open
    • Priority: Trivial Trivial
    • Resolution: Unresolved
    • Affects Version/s: 1.8-beta-1
    • Fix Version/s: None
    • Component/s: GroovyDoc
    • Labels:
      None
    • Number of attachments :
      0

      Description

      org.codehaus.groovy.ant.Groovydoc supports attributes like 'private'/'protected'/'public' but it seems like they are ignored in the gapi documentation generation. The documentation generated contains package-private details too, which it should not.

      For more related information, see GROOVY-4135.

        Issue Links

          Activity

          Hide
          Roshan Dawrani added a comment -

          Sure. I will try taking the scope related changes forward.

          Show
          Roshan Dawrani added a comment - Sure. I will try taking the scope related changes forward.
          Hide
          Guillaume Laforge added a comment -

          The grammar changes will require quite some work so we can integrate that in Groovy, so it's not for today.

          Show
          Guillaume Laforge added a comment - The grammar changes will require quite some work so we can integrate that in Groovy, so it's not for today.
          Hide
          Paul King added a comment -

          Yes, minimal error handling of the strange cases is in place, e.g. multiple settings. Plus the access scope is mostly respected - so the recently discussed classes like NodeChildren will be gone.

          There are some things which perhaps need further discussion. For Groovy classes I suspect people will be expecting 'public' to be missing. At the moment we still leave public on at the top most class level (perhaps we should turn that off - e.g. look at CliBuilder) but off for e.g. methods. Currently Java is done the same way but perhaps people expect the methods to be public as per normal Java conventions (e.g. look at a method in Expando). The isGroovy flag will help with this (but we also need a reference between members and the defining class - there is an incomplete hook for that already).

          Just on overall design, I think there are two approaches we can take as we evolve Groovydoc further. One path we can take is to make the Java follow Groovy conventions. After all, why should I know or even care about what the base language is and won't getting rid of some of the noise assist making the Java easier to read? Perhaps, but it gives us no way to distinguish Java specific things like package private.

          So, the other approach is to treat the two languages differently, which is mostly what we do now. For this to really work better, I think we need some more visual clues so that I can tell whether I am in Groovy and have something public or in Java and have package private. At the moment, it would be hard to tell. So, I think we need to work on that too. Perhaps some refinement of the CSS colors or perhaps a Java vs Groovy icon or some other indication on the page itself.

          Show
          Paul King added a comment - Yes, minimal error handling of the strange cases is in place, e.g. multiple settings. Plus the access scope is mostly respected - so the recently discussed classes like NodeChildren will be gone. There are some things which perhaps need further discussion. For Groovy classes I suspect people will be expecting 'public' to be missing. At the moment we still leave public on at the top most class level (perhaps we should turn that off - e.g. look at CliBuilder) but off for e.g. methods. Currently Java is done the same way but perhaps people expect the methods to be public as per normal Java conventions (e.g. look at a method in Expando). The isGroovy flag will help with this (but we also need a reference between members and the defining class - there is an incomplete hook for that already). Just on overall design, I think there are two approaches we can take as we evolve Groovydoc further. One path we can take is to make the Java follow Groovy conventions. After all, why should I know or even care about what the base language is and won't getting rid of some of the noise assist making the Java easier to read? Perhaps, but it gives us no way to distinguish Java specific things like package private. So, the other approach is to treat the two languages differently, which is mostly what we do now. For this to really work better, I think we need some more visual clues so that I can tell whether I am in Groovy and have something public or in Java and have package private. At the moment, it would be hard to tell. So, I think we need to work on that too. Perhaps some refinement of the CSS colors or perhaps a Java vs Groovy icon or some other indication on the page itself.
          Hide
          Paul King added a comment -

          Also, on the grammar changes. They will mostly improve the ability to process the content inside comments. E.g. extracting the @author tags easily rather than regex scrapping the information and keeping such info in its own data structure - helpful for smart @link's etc. The other processing, e.g. modifiers, method processing etc. won't be affected so much. There was also discussion about a doclet approach but that is also a long way off at the moment.

          Show
          Paul King added a comment - Also, on the grammar changes. They will mostly improve the ability to process the content inside comments. E.g. extracting the @author tags easily rather than regex scrapping the information and keeping such info in its own data structure - helpful for smart @link's etc. The other processing, e.g. modifiers, method processing etc. won't be affected so much. There was also discussion about a doclet approach but that is also a long way off at the moment.
          Hide
          Paul King added a comment -

          The isGroovy flag is now in SimpleGroovyClassDoc and there is a visibility indicator [Groovy] or [Java] before each class declaration in the GroovyDoc. This will enable us to start correcting want the temples do, e.g. no 'public' in front of a normal Groovy class but retain for a Java class. And so forth for methods etc.

          Show
          Paul King added a comment - The isGroovy flag is now in SimpleGroovyClassDoc and there is a visibility indicator [Groovy] or [Java] before each class declaration in the GroovyDoc. This will enable us to start correcting want the temples do, e.g. no 'public' in front of a normal Groovy class but retain for a Java class. And so forth for methods etc.

            People

            • Assignee:
              Unassigned
              Reporter:
              Roshan Dawrani
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated: