HI David, basically I would have to move the comments of:
https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150 and add the same ones here : https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105 , only in the format of asciidoc . so for this for example, you would also have to convert to asciidoc: https://github.com/apache/tomee/blob/master/container/openejb-jee/src/main/java/org/apache/openejb/jee/AbsoluteOrdering.java#L27L44 -- *Daniel Dias dos Santos* Java Developer SouJava & JCP Member GitHub: https://github.com/Daniel-Dos Linkedin: www.linkedin.com/in/danieldiasjava Twitter: http://twitter.com/danieldiasjava Em dom, 9 de dez de 2018 às 19:00, David Blevins <david.blev...@gmail.com> escreveu: > > 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 > >
