> On Dec 9, 2018, at 9:48 AM, David Blevins <david.blev...@gmail.com> wrote: > >> - Write Javadocs in Asciidoc
I created a "Wish" JIRA for this one and detailed some steps: - https://issues.apache.org/jira/browse/TOMEE-2347 That would be for the main build. Here's a separate JIRA for doing that in the Javadoc generator we need for the website: - https://issues.apache.org/jira/browse/TOMEE-2343 Some background on my goofy thinking. Let me try and be as succinct as possible without losing everyone. Here's the story of just one configuration property, `maxAge` on the Stateless container. ## MaxAge Search this page for the phrase "this will happen gracefully" where `maxAge` is defined. - http://tomee.apache.org/tomee-8.0/docs/statelesscontainer-config.html That page was generated from this file which has Markdown embedded in it: - https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150 Here's the actual piece of code that should probably have that Markdown (or asciidoc) as Javadoc: - https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105 ## Issues Our effort to maintain the documentation for the MaxAge setting is a little high IMO because a few things: - the documentation for `maxAge` is not as close to the code as possible. You need to know about the existence of the `service-jar.xml`. - the code that generated the file `docs/statelesscontainer-config.adoc` in our source is hard or impossible to find. You need to know that file was generated from the service-jar.xml and know where the code is that did this work. I wrote that code, but I don't remember where it is or if I even kept it. If we changed the definition of `maxAge`, doing "the right thing" would involve updating: - html formatted javadoc on `StatelessContainerFactory#setMaxAge` - markdown formatted comments in service-jar.xml - asciidoc formatted description in `docs/statelesscontainer-config.adoc` ## The very tempting solution Ideally, you just write Javadoc and "the right thing happens" even if you don't know how. The very tempting solution is to take the asciidoc from `docs/statelesscontainer-config.adoc` and: - push it onto the `StatelessContainerFactory.java` file as javadoc - delete the `docs/statelesscontainer-config.adoc` file - delete the related comments from `service-jar.xml - write some code so JBake can generate `docs/statelesscontainer-config.html` using mostly the javadoc in `StatelessContainerFactory.java` It's slightly crazing thinking, I know, but that's me :) -David
