Maven Javadoc Plugin
  1. Maven Javadoc Plugin
  2. MJAVADOC-78

Add a flag to provide standard doclet parameters to custom ones too

    Details

    • Type: Improvement Improvement
    • Status: Closed Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 2.0
    • Fix Version/s: 2.5
    • Labels:
      None
    • Number of attachments :
      2

      Description

      I'm working on a custom doclet that wraps the standard doclet and add extra behaviour (automated class diagram generation in class javadocs and package javadocs). I want to run it under maven 2, but I've stumbled against the default behaviour: standard doclet parameters such as -link are provided only if the javadoc is the standard one (in AbstractJavadocMojo.java, the check is "if ( StringUtils.isEmpty( doclet ) ) ...").

      A generally good behaviour would be not perform assumptions, but to call XXXDoclet.optionLength for each parameter, and see if the doclet accepts them or not (and thus provide only the one accepted). As an alternative, add at least a flag to allow the provision of the standard doclet parameters to the custom ones as well.

      1. JAVADOC-78.patch
        2 kB
        Vincent Siveton
      2. pom.xml
        31 kB
        Andrea Aime

        Activity

        Hide
        Steven Coco added a comment -

        I would add that I also think this is needed. Another reason is that you may actually specify what is the default doclet, but the mere presence of the doclet element blocks the default parameters from being used. Such a configuration was useful when recently the javadoc plugin did not use the default doclet behavior by default; and if you wanted the default output provided by your JDK then you had to explicitly specify it – and then these swithces were not passed to the doclet. Note that I actually don't know what Maven is now using as the default doclet since I haven't actually checked into it, but it now at least appears to be the default one – there is a new color scheme since 5.0 that now is being used in Maven's output.

        The suggestion noted above sounds great. Frankly though, simply always passing whatever has been declared sounds fine to me, even if an exception results, since this should be expected by anyone declaring these attributes alongside one another. Exceptions are always acceptable.

        Show
        Steven Coco added a comment - I would add that I also think this is needed. Another reason is that you may actually specify what is the default doclet, but the mere presence of the doclet element blocks the default parameters from being used. Such a configuration was useful when recently the javadoc plugin did not use the default doclet behavior by default; and if you wanted the default output provided by your JDK then you had to explicitly specify it – and then these swithces were not passed to the doclet. Note that I actually don't know what Maven is now using as the default doclet since I haven't actually checked into it, but it now at least appears to be the default one – there is a new color scheme since 5.0 that now is being used in Maven's output. The suggestion noted above sounds great. Frankly though, simply always passing whatever has been declared sounds fine to me, even if an exception results, since this should be expected by anyone declaring these attributes alongside one another. Exceptions are always acceptable.
        Hide
        Steven Coco added a comment -

        What a bizarre icon showed up! I didn't mean to make a warning sign in the above comment; sorry. I typed an exclamation point in parentheses...

        Show
        Steven Coco added a comment - What a bizarre icon showed up! I didn't mean to make a warning sign in the above comment; sorry. I typed an exclamation point in parentheses...
        Hide
        Vincent Siveton added a comment -

        Here is a proposed patch. Is it enough for your use case?
        Could you also send us a test case, so I could include it?

        Show
        Vincent Siveton added a comment - Here is a proposed patch. Is it enough for your use case? Could you also send us a test case, so I could include it?
        Hide
        Andrea Aime added a comment -

        I don't have exactly a test case, but I can attach the pom that we had to make to make things work, as you can see there is a profile that activates the usage of the special doclet and reconfigures the javadoc plugin accordinly (see the javadoc config in build and then the "uml" profile near the end).

        Show
        Andrea Aime added a comment - I don't have exactly a test case, but I can attach the pom that we had to make to make things work, as you can see there is a profile that activates the usage of the special doclet and reconfigures the javadoc plugin accordinly (see the javadoc config in build and then the "uml" profile near the end).
        Hide
        Vincent Siveton added a comment -

        If not already done, could you try the patch and give us your comments?

        Show
        Vincent Siveton added a comment - If not already done, could you try the patch and give us your comments?
        Hide
        Trustin Lee added a comment -

        The patch looks OK, but is there any reason that validateStandardDocletOptions() is not called if a custom doclet is specified with useStandardDocletOptions?

        Show
        Trustin Lee added a comment - The patch looks OK, but is there any reason that validateStandardDocletOptions() is not called if a custom doclet is specified with useStandardDocletOptions?
        Hide
        Trustin Lee added a comment -

        The workaround for this issue is to specify all options in <additionalparam>:

        which is painful. I'd love to see this patch applied to the next release.

        Show
        Trustin Lee added a comment - The workaround for this issue is to specify all options in <additionalparam>: http://code.google.com/p/apiviz/#Maven_2_Integration which is painful. I'd love to see this patch applied to the next release.
        Hide
        Vincent Siveton added a comment -

        Fixed in r680869, snapshot deployed.
        FYI I plan to make a release this week. So could you test it for your requirements? tx

        Show
        Vincent Siveton added a comment - Fixed in r680869 , snapshot deployed. FYI I plan to make a release this week. So could you test it for your requirements? tx

          People

          • Assignee:
            Vincent Siveton
            Reporter:
            Andrea Aime
          • Votes:
            3 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: