My guess would be the site manual. So we should be careful in how much detail to reveal on the site manual.
For example, I deliberately did not write the path and file name of the plugins metadata file (Log4j2Plugins.dat). I noticed that the full path of that file is mentioned in the plugins manual page after applying Scott's LOG4J2-745 patch. Would it not be better to keep that an undocumented implementation detail ? Sent from my iPhone > On 2014/08/07, at 13:46, Matt Sicker <[email protected]> wrote: > > 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 >>> JUnit in Action, Second Edition >>> Spring Batch in Action >>> Blog: http://garygregory.wordpress.com >>> Home: http://garygregory.com/ >>> Tweet! http://twitter.com/GaryGregory > > > > -- > Matt Sicker <[email protected]>
