> 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

Reply via email to