Support any @Documentation

[rmannibucau]

Hi,

idea is to be able to put @documentation on the resource and method and integrate the value() automatically as the description of the decorated resource. Package shouldn't be important and up to the project. Only constraint would be to be @retention(RUNTIME) and to have a String value() method.

[sdaschner]

The idea was to use JavaDoc for this -- which basically works, but introduced quite some issues, all due to the (horrible) JavaDoc parser. The JavaDoc parser needs to be replaced by a more stable solution...
Also see #109

I'd vote for not adding custom annotations that projects have to include, this would introduce dependencies to our tool. The same was my intention for not supporting Swagger annotations btw.

Thoughts?

[rmannibucau]

Well intention was not to introduce a jaxrs-analyzer annotation but just use any @documentation#value found on the methods/classes.

[sdaschner]

Ah, I see!
Well, I would say, providing JavaDoc is even a cleaner fit for projects, rather than using that annotation, right?

[rmannibucau]

Hmm, 2 points then:

• i didnt use javadoc since years since it is bound to a particular techno
• javadoc has an intendez usage which is not this one so better to keep it split IMO. You can argue we can add a specific tag bit then we are at the same stage. Add it is easier for apps to use reflection to generate their doc and then supporting @doc would enable more usages than javadoc :)

[rmpestano]

Hi guys, just my opinion below:

"I didnt use javadoc since years since it is bound to a particular techno"

isn't this project tied to a particular tech (Java/JaxRS)? or It can be used with other stack?

javadoc has an intendez usage which is not this one so better to keep it split IMO

I really think it is a great place for JavaDoc and that's one of the main advantages of this plugin IMO, to not polute your API with documentation tags. With JavaDoc it is clear that it is not part of the API.
On the other hand if you use Swagger annotations e.g @Api you need to filter/Ignore those annotations while reading code and the oposite is also true when you want to focus on Api Docs you need to look only into Docs annotations, for me a complete mess.

[rmannibucau]

This project is bound to a techno but javadoc is used for another usage (clearly not http doc but java doc ;)). If you put it in jdoc the filteeing is way harder since you need to filter a single location vs some explicit ones.

Thinking about it, just being able to insert a placeholder the build can replace (like a unique adoc attribute for adoc rendering, comment for html etc..) can be enough and avoid any particular API support. This way apps can just set the placeholder value at rendering time.

[sdaschner]

Please see update in #109

@rmannibucau what placeholder are you thinking about? e.g. custom JavaDoc tags?

[rmannibucau]

Please nothing related to javadoc :).

Was more thinking about a variable in the generated adoc wich can be valorised through the adoc rendering (using attributes)

[rmannibucau]

up? An API which is not required to be delivered at the end (war/classpath) is not very hard to do since java doesn't load missing annotations and it would avoid to mix dev comments (javadoc) and API documentation. Since the people have different expectations we must use two sources IMHO. A fallback would be to use a swagger tag in the javadoc and put all the API doc in there but it looks quite ugly to have tested on a few endpoints. An interesting alternative can be a synch option with a file in the sources (src/main/swagger/swagger.*). If a resource is deleted from sources the maven plugin can delete it from the file, if it is added then it is added to the file and if it changes then it merge the generated one (path, method, params etc...) and user updates (comments, description, ....).

Would be great to finally be able to fix this user facing point :).