Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.1
    • Labels:
      None

      Activity

      Hide
      Brett Porter added a comment -

      good job!

      feedback:

      • please add more on the index page (include link to usage and examples)
      • 'mvn javadoc:jar' should use <<<code style>>>
      • typo on maxmemory example for usage
      • put reporting first as the primary use case
      • move javadoc:jar to last, and mention that it is run by default and mostly used when releasing to publish to the repository
      • Try and use more explanatory titles for the examples, eg "Aggregating Javadoc for Multiple projects"
      • use 'tree' for tree structures (see MWAR-48 for explanation)
      • the links for the examples other than the first one are broken.
      Show
      Brett Porter added a comment - good job! feedback: please add more on the index page (include link to usage and examples) 'mvn javadoc:jar' should use <<<code style>>> typo on maxmemory example for usage put reporting first as the primary use case move javadoc:jar to last, and mention that it is run by default and mostly used when releasing to publish to the repository Try and use more explanatory titles for the examples, eg "Aggregating Javadoc for Multiple projects" use 'tree' for tree structures (see MWAR-48 for explanation) the links for the examples other than the first one are broken.
      Hide
      Maria Odea Ching added a comment -

      Thanks Will apply the comments above..

      Show
      Maria Odea Ching added a comment - Thanks Will apply the comments above..
      Hide
      Maria Odea Ching added a comment -

      Applied the comments above. Also revised some of the pages like the usage and the examples docs.

      Show
      Maria Odea Ching added a comment - Applied the comments above. Also revised some of the pages like the usage and the examples docs.
      Hide
      Brett Porter added a comment -

      This is almost there.

      feedback:

      • rename overview to index
      • comment out FAQ until there are some
      • 'mvn javadoc:jar' should use <<<code style>>> and remove 'quotes' on usage page (and other similar ones)
      • the links for the examples other than the first one are broken.
      Show
      Brett Porter added a comment - This is almost there. feedback: rename overview to index comment out FAQ until there are some 'mvn javadoc:jar' should use <<<code style>>> and remove 'quotes' on usage page (and other similar ones) the links for the examples other than the first one are broken.
      Hide
      Brett Porter added a comment -

      also:

      • links to goal references don't work
      Show
      Brett Porter added a comment - also: links to goal references don't work
      Hide
      Maria Odea Ching added a comment -

      The problem with the broken links in the examples (with mvn site:run) were the filenames of the apt files. Before, the filenames had uppercase letters in it (e.g. excludePackageNames.html), but when I changed it to all lowercased (e.g. excludepackagename.html) the links were fine. Could this be a bug with the site plugin?

      Show
      Maria Odea Ching added a comment - The problem with the broken links in the examples (with mvn site:run) were the filenames of the apt files. Before, the filenames had uppercase letters in it (e.g. excludePackageNames.html), but when I changed it to all lowercased (e.g. excludepackagename.html) the links were fine. Could this be a bug with the site plugin?
      Hide
      Maria Odea Ching added a comment -

      Btw, I've already committed the changes I've made from the suggested revisions above. Thanks

      Show
      Maria Odea Ching added a comment - Btw, I've already committed the changes I've made from the suggested revisions above. Thanks
      Hide
      Brett Porter added a comment -
      • the FAQ and usage both refer to having to be in the build section. This is only necessary if the configuration will be different to on the site, or the report not on the site at all.
      • there's some inconsistency between "Usage" and "How to Use" between the plugins that have been submitted recently. I think I prefer "Usage"... WDYT?
      Show
      Brett Porter added a comment - the FAQ and usage both refer to having to be in the build section. This is only necessary if the configuration will be different to on the site, or the report not on the site at all. there's some inconsistency between "Usage" and "How to Use" between the plugins that have been submitted recently. I think I prefer "Usage"... WDYT?
      Hide
      Maria Odea Ching added a comment -

      I think "Usage" is better and more descriptive.. I'll just update the docs and apply the comments above. Thanks!

      Show
      Maria Odea Ching added a comment - I think "Usage" is better and more descriptive.. I'll just update the docs and apply the comments above. Thanks!
      Hide
      Maria Odea Ching added a comment -

      Additional review comments in the mailing list from Dennis Lundberg were not applied in the documentation.

      I've read through the docs and here are some comments:

      All

      • The title for all pages is "Maven Javadoc Report", but all references in the text refers to Maven Javadoc Plugin.

      usage.html

      • Do we need to include the configuration section in the sample pom? There is no mention of the max/minmemory settings in the text.

      jar-mojo.html

      • This page is very wide, wider than my 1280 screen. The reason is the "groups" param example code, and also the "tags" example. I see in the source code that there are line breaks inside the pre-tag, but they seem to be ignored. Perhaps a bug in the plugin plugin or the used javadoc parser?
      • finalName param: "Specified the" -> "Specifies the"
      • nocomment param: "Ssee" -> "See"
      • nonavbar param: Seems to be copy-and-pasted from "noindex" + two default values
      • old param: "This option created" -> "This option creates"
      • windowtitle param: two default values

      examples/*.html (except alternate-doclet.html)

      • The poms in these examples have the javadoc plugin configured in the build section. Shouldn't it be the reporting section?


      Dennis Lundberg

      Show
      Maria Odea Ching added a comment - Additional review comments in the mailing list from Dennis Lundberg were not applied in the documentation. I've read through the docs and here are some comments: All The title for all pages is "Maven Javadoc Report", but all references in the text refers to Maven Javadoc Plugin. usage.html Do we need to include the configuration section in the sample pom? There is no mention of the max/minmemory settings in the text. jar-mojo.html This page is very wide, wider than my 1280 screen. The reason is the "groups" param example code, and also the "tags" example. I see in the source code that there are line breaks inside the pre-tag, but they seem to be ignored. Perhaps a bug in the plugin plugin or the used javadoc parser? finalName param: "Specified the" -> "Specifies the" nocomment param: "Ssee" -> "See" nonavbar param: Seems to be copy-and-pasted from "noindex" + two default values old param: "This option created" -> "This option creates" windowtitle param: two default values examples/*.html (except alternate-doclet.html) The poms in these examples have the javadoc plugin configured in the build section. Shouldn't it be the reporting section? – Dennis Lundberg
      Hide
      Maria Odea Ching added a comment -

      Applied the comments above in the plugin docs. The staging site has also been updated http://people.apache.org/~oching/maven-javadoc-plugin
      Thanks

      Show
      Maria Odea Ching added a comment - Applied the comments above in the plugin docs. The staging site has also been updated http://people.apache.org/~oching/maven-javadoc-plugin Thanks
      Hide
      Wendy Smoak added a comment -

      Change the example on the alternate doclet page to one that works with the newly released version of UmlGraph.

      Separate reportsets are no longer necessary, UmlGraphDoc now generates UML diagrams as part of the Javadoc.

      Show
      Wendy Smoak added a comment - Change the example on the alternate doclet page to one that works with the newly released version of UmlGraph. Separate reportsets are no longer necessary, UmlGraphDoc now generates UML diagrams as part of the Javadoc.
      Hide
      Maria Odea Ching added a comment -

      Updated the alternate doclet page and the staging site http://people.apache.org/~oching/maven-javadoc-plugin.

      Show
      Maria Odea Ching added a comment - Updated the alternate doclet page and the staging site http://people.apache.org/~oching/maven-javadoc-plugin .

        People

        • Assignee:
          Maria Odea Ching
          Reporter:
          Maria Odea Ching
        • Votes:
          0 Vote for this issue
          Watchers:
          0 Start watching this issue

          Dates

          • Due:
            Created:
            Updated:
            Resolved:

            Time Tracking

            Estimated:
            Original Estimate - Not Specified
            Not Specified
            Remaining:
            Remaining Estimate - 0h
            0h
            Logged:
            Time Spent - 34h
            34h

              Development