Now when you say manual, do you mean the site manual or the javadocs?
On 5 August 2014 08:20, Ralph Goers <[email protected]> wrote: > Well, in my view there are two kinds of public. 1) the API users code to > add logging to their code, 2) the API they code to to create Layouts, > Appenders, Filters and other plugins. In short, if itis documented in the > manual it should be considered public. > > Ralph > > On Aug 5, 2014, at 6:01 AM, Gary Gregory <[email protected]> wrote: > > 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 > > -- Matt Sicker <[email protected]>
