I think the separation we have so far is that log4j-api is "public" and everything else not. We can provide more fine grained definitions of course.
Gary On Tue, Aug 5, 2014 at 8:55 AM, Matt Sicker <[email protected]> wrote: > Oh, I know what you mean. However, sometimes documentation is useful for > internal use. Is it enough to mark particular classes as internal? Like > with an annotation or just in the javadoc or something. Annotation or > javadoc tag could be used during site generation to handle them as > something special. > > > On 5 August 2014 06:31, Gary Gregory <[email protected]> wrote: > >> Cool. I am disapointed at the lack of docs in some FOSS projects, so it's >> good to see someone stepping up. >> >> That said, keep in mind that some people consider Javadoc to be a >> contract definition, and that modifying something that is doc'ed in a >> future release is a break in compatibility. >> >> So let's be careful in what we document and how. I do not think we have >> documented what our policy is on that though. I'm am just worried that if >> we doc the internal workings of some method or class, users will then rely >> on that behavior and complain if it changes. Aside from that, doc away! >> >> Gary >> >> >> -------- Original message -------- >> From: Matt Sicker >> Date:08/04/2014 22:36 (GMT-05:00) >> To: Log4J Developers List >> Subject: In regards to javadoc updates. >> >> So as you may have already noticed, I like to write a lot. This carries >> over to documentation, and I prefer javadocs when it comes to that as it's >> far easier to keep in sync with how the code works. With that in mind, I've >> been elaborating about random classes to help improve the docs. However, >> since I'm obviously not the author of everything here by any means, I might >> misinterpret classes or functions slightly. If I do, please let me know! >> >> As a developer, I usually skip straight to the javadocs for any library I >> use, and I'm oftentimes disappointed by the lack of documentation in them. >> Examples can become stale over time. A good majority of the JDK is well >> documented (there are several exceptions of course), and I like to try to >> follow that pattern myself. >> >> -- >> Matt Sicker <[email protected]> >> > > > > -- > Matt Sicker <[email protected]> > -- E-Mail: [email protected] | [email protected] Java Persistence with Hibernate, Second Edition <http://www.manning.com/bauer3/> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/> Spring Batch in Action <http://www.manning.com/templier/> Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
