Documenting Business Logic using custom tag in JavaDoc?

Question

Is it possible to create a list of notes from a custom defined tag using JavaDoc? I have a business rules I want to flag throughout the code and it really doesn't fall under any of the existing tags that I know of. I suppose if there was a tag that did something similar to:

@note logic - You can only have twelve widgets in this container

It's sort of reverse documentation of constraints or requirements, and I'd like to document these because they weren't necessarily part of the original spec. One reason I'd like to document it in the source code is that the source code never seems to get lost, while the design spec, well... (not to mention nobody seems to read them)

Answer 1

Why not just put it in the normal Javadoc comments itself? As an explanation of the summary of the class, method, etc. This is perfectly acceptable and it is how most of the JDK itself is documented.

If that's not good enough for you, perhaps you could create a custom attribute to tag members/methods/classes with, then you could easily programatically scan the classes and find all of your notes.

@CustomNote("You can only have twelve widgets in this container")
public class WidgetContainer { 
    ...

Answer 2

XDoclet should be able to customized to what you want to do.

If you are using java 1.5+, you can use regular annotations, and compile them into a report. Here are instructions. That is definitely simpler than the XDoclet approach.