Hello Am Wed, 25 Nov 2009 20:13:58 -0600 schrieb Curt Arnold <[email protected]>:
> Got a couple of issues with the docs, in order of significance: > > > 1. No "Apache", version number or incubating disclaimer on generated > docs. The generated docs have a generic title "Generated > Documentation" and log4php stands by itself, really should be "Apache > log4php 2.0.0 (incubating)" or something like that. Fixed in r884717 > 2. No ASF header in generated docs > > From http://www.apache.org/legal/src-headers.html > > > What if my project includes its web site within a product > > distribution? > > > > With few exceptions, all human-readable Apache-developed files that > > are included within a distribution must include the header text. > > Documentation, including web site documentation distributed with > > the release, may include the header text within some form of > > metadata (such as HTML comments) or as a header or footer appearing > > in the visible documentation. > > Also > http://incubator.apache.org/guides/releasemanagement.html#notes-license-headers > > > > The issue of licenses on generated documentation is a little > > controversial. Copyright may not subsist in a document which is > > generated by an transformation from an original. In which case, the > > license header may be unnecessary. License headers should always be > > present in the original. Where it is reasonable to do so, the > > templates should also add the license header to the generated > > documents. > > > > > If the license header could be templated in as an HTML comment, it > would eliminate this as a point of contention. Oh, those license-o-maniacs are beginning to go me on my nerves! :-/ All source code files carry the license and if one clicks on "files" instead of "classes" they are shown. As I found no way to easily customize the generated HTML files, played around with the phpdoc tutorial function and found a way to alter the start page which now prints only the license. If that's not enough somebody else may spend his time on this. > 3. Generated docs placed in target/site directory. > > target is the default build directory for maven. Typically, the site > built with the release is placed in doc, leaving the target directory > available for end-user builds. Otherwise, it is easy for a Java > developer to inadvertently write over the released documentation. > The "includeSiteDirectory" descriptor in Maven's assembly plugin > isn't adequately described, but I'm guessing it works with the > javadoc plugin and does that relocation automatically, but it doesn't > do the same for phpdoc. Hmm... the maven-javadoc-plugin and maven-assembly-plugin as I know it from other projects always use the target/ directory. And if a programmer executes "mvn site" or similar, well then I would expect nothing else than that he of course overwrites the released api documentation as well as the released zip files because that's just what a build is supposed to. Or the other way around if a programmer deliberately changes something in our files then he expect changes in the apidocs and will be very confused when the one he has open in his browser (doc/apidocs/) will not change because we regenerated them in target/site/apidocs. Or maybe I misunderstood the point? > 4. PEAR doesn't include log4php.dtd Fixed in 884728. The new tutorial.pkg is still excluded but the PEAR package is not meant to used for building so that's ok. > 5. src/assembly/bin.xml has an obsolete name, src.xml would likely be > better. Fixed in 884729 > I'm thinking the cumulative is a -1 for me. Sorry I wasn't able to > pick this up sooner. Maven's RAT didn't pick up on the license > header since it doesn't check the target directory, it does if you > move target/site to doc. I don't know if standalone RAT would have > flagged it. > > I'm going to have some free time on Monday and Tuesday night, but am > likely out of touch till then. That were some well spotted issues. Maybe RC3 will finally make it :) bye, -christian-
