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]>
