> On Dec 9, 2018, at 2:10 PM, Daniel Dias Dos Santos > <daniel.dias.analist...@gmail.com> wrote: > > 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 .
That's one idea of the benefits of using Asciidoc in our Javadoc. The service-jar.xml specifically has been in the project for a long time, so it'd be great to hear more thoughts. However the general idea, which is bigger than service-jar.xml, is that the more we're pushing good documentation into the source code, the more opportunities we have to use it to feed docs on the website. Since the website documentation is primarily Asciidoc, lining that up with our Javadoc could be very smart. We don't necessarily have to switch the comments in the service-jar.xml over as a first step. The first step could be to simply start writing Javadoc for classes that don't have them. > 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 In my opinion, the JAXB-generated Javadoc is of low to no value and could just be deleted. -David