Add support for reading documentation from the Javadoc

[ST-DDT]

Writing descriptions inside annotations is pretty ugly, thats why I thought that it should somehow be possible to generate a javadoc format that can be picked up by livedoc and thus shown as description texts.

Requirement/Requested feature

• JSON-javadoc formatter
• Enrich livedocs using JSON metadata

Source

/**
 * This is a controller.
 * <p>Note: This is an example.</p>
 */
@RestController
@RequestMapping("foobar")
public class FoobarController {

    /**
     * Foobar does foo a bar.
     *
     * @param stuff The stuff to show.
         * @return The given stuff.
     */
    @RequestMapping(path = "/{stuff}", method = RequestMethod.GET)
    public String list(@NotBlank @PathVariable("stuff") final String stuff) {
        return stuff;
    }

}

Processing

mvn livedoc:javadocjson

Result: target/generated-resources/com/example/foo/controller/FoobarController

{
"name": "FoobarController",
"description": "This is a controller.\n<p>Note: This is an example.</p>",
"methods": [
    {
    "name":"java/lang/String;list(java/lang/String)", // Whatever
    "description":"Foobar does foo a bar.",
    "parameters":[...]
    }
]

Configuration

LiveDocController.enableFileMetaDataSearch()

Result

Would be similar to writing it in the annotations. (I cannot make a screenshot right now)

[joffrey-bion]

I share your opinion, and I really wanted to do it this way too when I started revamping JsonDoc.

The first problem was that I wanted Livedoc's processing to be executable at runtime, but we can't process javadoc at runtime. That being said, I'm more and more leaning towards a generation of the json at build time, or at least most of the doc (the base URL may still need to be generated at runtime).

Also, I'm not sure about what the javadoc tool from the jdk offers, but I imagine they don't provide the internal representation of the javadoc structure, which means that would require parsing either the source code or the javadoc HTML output. There is probably some library for this out there.

I should do some research on that last aspect, or maybe you already know about something? First, I need to focus on the last refac of the react frontend before being able to (at last) release Livedoc v4.

[ST-DDT]

A first google search revealed https://github.com/rob4lderman/javadoc-json-doclet

[joffrey-bion]

In fact, I found an interesting annotation processor that generates classes to store the javadoc for the runtime: therapi-runtime-javadoc. This way, no need for JSON generation in the middle + parsing at runtime, a simple method call gives the Javadoc represented with Java objects.

I managed to use this in Livedoc to get class and method descriptions, and I'll try to add param descriptions this week. Then comes the problem of packaging, I'll look into gradle's annotation processor configuration and see what I can do with this.

One of the problems I see so far is that the user needs to annotate every class of the model manually with @RetainJavadoc in order for Livedoc to be able to get descriptions from the javadoc. This lib doesn't not work with a package whitelist, which is a pity, I'll see if I can contribute to that project in order to get this feature. It doesn't seem to hard to implement. It would be too bad to have to annotate everything, since we just managed to provide an annotation-free solution.

The dependency on therapi-runtime-javadoc can be eliminated by using @RetainJavadoc as a meta-annotation on a custom Livedoc annotation, so that should not be a problem.