Support for reusing repeating documentation snippets

[xkacer]

We have quite a big API here and many parts of the documentation repeat in several places. A typical example are descriptions of response error codes. Currently, we preprocess source codes before passing them to Enunciate, which allows us to expand some kind of "macros" to longer text defined in one place. However, it would be nice to get rid of this preprocessing and let Enunciate do the job.

It took me some time to come up with something general enough to believe it could be implemented as an Enunciate enhancement and used also by others. The following points are partially independent but all of them are related, so I only create a single issue here.

1. Support DocumentationType and DocumentationExample (both annotation and javadoc tag) not only for members but also for types. I think this one is quite natural: If there is no documentation example/type declared on a field ("member"), use the one from the class javadoc of the field type. Particularly handy for special types that serialize as strings, but also for polymorphic types and other cases. Beside serving as a default for members, the documentation example on a class would also be used on the documentation page describing the class itself.

2. Allow to replace @see with predefined snippets of javadoc. Ideally, the snippet should be allowed to contain other javadog tags. There are many possible use cases of this feature. One example for all is handling of error codes. The method javadoc would contain @see MyErrorCode#NOT_FOUND which makes it nice in IDE, as a programmer can click the link and see the error code documentation in source code. Then, in enunciate.xml, we would specify the replacement by something like: <expand-see key="MyErrorCode#NOT_FOUND">@HTTP 404 the specified object was not found</expand-see> and the generated documentation will automatically contain the same description in all places.

3. Allow to expand annotations to javadoc snippets. This is actually similar to the previous one, but annotations are used insted of javadoc @see tag. Again, I can imagine many examples of using this. For instance, you may generate a nice warning box to all @Deprecated methods.

What are your thoughts? Again, I am willing to try to implement these improvements, if you find them reasonable. However, I'd probably need some help, especially with the first one.

[stoicflame]

Seems reasonable.

You're welcome to put together a PR for me to look at if you want.

#1 would probably an edit of com.webcohesion.enunciate.modules.jackson.model.util.JacksonUtil#findAdapterType(javax.lang.model.element.Element, com.webcohesion.enunciate.modules.jackson.EnunciateJacksonContext) to support @documentationType and an edit of com.webcohesion.enunciate.modules.jackson.api.impl.DataTypeExampleImpl to support @documentationExample.

#2 and #3 would be an extensive edit to com.webcohesion.enunciate.javac.javadoc.JavaDoc to support "macros".

[stoicflame]

This enhancement is currently seeking a sponsor. If anybody is willing to sponsor the work, reach out to me and I'd be happy to pick it up.