[JAMES-2325] Allow to exclude some matcher/mailet from documentation

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: master
• Fix Version/s: 3.2.0
• Component/s: Documentation, Mailet Contributions
• Labels: docuentation feature newbie
• Assignee: Unassigned
• Reporter: Benoit Tellier
• Created: 01/Feb/18 04:31
• Updated: 24/Oct/18 09:46
• Resolved: 24/Oct/18 09:46

Description

Apache James uses the `mailetdocs-maven-plugin` in order to build the mailet/matcher documentation.

This plugin scans the sources, finds mailet and matcher, then generates the documentation entry from its javadoc.

Nowadays all mailet and matchers are included.

This is a problem because we have some test specifics mailets/matcher that are not usable as part of James but still are reported as part of the documentation.

(Examples includes james-project/server/container/guice/custom-mailets/src/main/java/org/apache/james/transport/mailets/CustomMailet.java and the like, used to generate a separate library containing custom mailets/matchers in order to test custom mailets/matchers instanciation)

The goal of this ticket is to add a `@ExcludeFromDocumentation` annotation as part of the mailet-api. The plugin would skip such annotated mailets/matcher.

In order to to this:

• Create a new `@ExcludeFromDocumentation` in the mailet API
• Annotate with it classes in `james-project/server/container/guice/custom-mailets`
• Modify james-project/mailet/mailetdocs-maven-plugin/src/main/java/org/apache/james/mailet/DefaultDescriptorsExtractor.java in order to skip classes annotated as excluded.
• Add a test in james-project/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/DefaultDescriptorsExtractorTest.java showing excluded mailets are not listed (add an excluded mailet in that package, then assert in a new test that it is not reported).

As always we stay at your disposal to answer any question on the chat! https://gitter.im/apache/james-project