Hi Harald, see my comments inline
regards, Achim 2011/8/21 Harald Wellmann <[email protected]>: > Am 19.08.2011 15:31, schrieb Achim Nierbeck: > >> you are certainly right that we could need something like this. But >> right now I don't see the real advantages of it. >> The javadoc artefacts are published to maven central. So what a dev >> really needs the proper javadoc while coding >> is already there. >> > > Maven Javadoc artifacts are fine, the question is just how to make them more > accessible. For developers, the IDE might take care of that, but I'd really > like to see all OPS4J Javadocs published under a canonical HTTP URL so you > can simply link to the Javadocs from elsewhere, e.g. the OPS4J Wiki. > > (For Eclipse+m2e users, there is an option "Maven|Open Javadoc" in the > context menu of a Maven dependency, which I hadn't been aware of and which > works fine.) > > https://oss.sonatype.org serves Javadoc pages directly from Maven artifacts > but you need to be logged in with a Sonatype OSS account in order to use it > :-( > > Example: > https://oss.sonatype.org/service/local/repositories/ops4j/archive/org/ops4j/pax/exam/pax-exam/2.1.0/pax-exam-2.1.0-javadoc.jar/!/index.html > > Maybe there's a chance of convincing Sonatype to let anonymous users access > these URLs....? > >> The thing about uploading this HTML stuff is not as simple as it might >> look at first glance. >> First of all we need the server infrastructure for it and time and >> know how to keep it going, >> second we probably also need a specialized account for uploading this >> HTML stuff cause >> we certainly don't want our server infrastructure (at least what is >> left) be compromised again. >> > > Publishing a bunch of static HTML on a webserver shouldn't be too > difficult... > well, shouldn't but every-time a artifact is build it needs to be published, and actually I don't want everybody to be able to do so. Just because they are able to build an release shouldn't allow them to deploy on our infrastructure. In the past we had some hackers attacking the system therefore I don't think we need to open this window :-) > If we can't use an existing server for this purpose or are afraid of > creating new security risks by setting up a new server, there's at least 2 > simple options: > > 1) Hudson Javadoc Archiver in combination with the Promoted Builds plugin. > Promoting all release builds would then automatically produce stable URLs > for the corresponding Javadocs. again the build server would need credentials to publish. Just another possibility to go for sniffing, I really don't like right now. One thing I certainly don't want is to configure user credentials on a system like this. So it leaves only the one option that certain people know the credentials to the system. Right now this number is very tight and I don't think it's really worth giving this people even more work to upload all javadocs. > > 2) Commit Javadocs to the source repository. Not exactly best pratice, but > that's what many projects do, e.g. Mockito on Google Code. > > Unfortunately, Github makes this harder than it should be. URLs like > > https://raw.github.com/kevinweil/elephant-bird/master/javadoc/index.html > > seem to be missing the HTML content header, so you have to do some extra > setup, see > > http://xlson.com/2010/11/09/getting-started-with-github-pages.html > sounds like a real hack -1 :( >> So since we all are pretty much lacking the know-how and time to do >> >> proper administration >> I'm sure it is OK to keep it the way it is right now. >> >> Regarding the amount of documentation. Yep you are certainly right >> that it could / needs improvements. >> But hey, making it public won't make it better, I'm for sure. >> > > I'm not satisfied with the current status, or else I wouldn't have raised > this topic. > > Javadoc is just one facet of improving the general level of documentation > for Pax projects, and lack of documentation is the weakest point of Pax, > IMHO. > > The Wiki is the best place for tutorials and overviews, but for detailed > reference, keeping the documentation in the source code (via Javadoc > comments) and linking to the generated Javadocs from the Wiki saves time and > effort and avoids redundancy. > > Example: I've started documenting the Pax Exam configuration options in > > http://team.ops4j.org/wiki/display/paxexam/Configuration+Options > > but I'd much rather simply link to the Javadoc of > org.ops4j.pax.exam.CoreOptions instead. > > Ok, the Javadoc of this class is pretty self-referential and useless at the > moment, but this is a chicken-and-egg type of problem. > > Not being able to publish Javadoc should not be an excuse for writing poor > doc comments or omitting them. > > If I can't be bothered to document my code, why should anyone bother to read > or use it? > > Best regards, > > Harald > > _______________________________________________ > general mailing list > [email protected] > http://lists.ops4j.org/mailman/listinfo/general > -- -- *Achim Nierbeck* Apache Karaf <http://karaf.apache.org/> Committer & PMC OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/> Committer & Project Lead blog <http://notizblog.nierbeck.de/> _______________________________________________ general mailing list [email protected] http://lists.ops4j.org/mailman/listinfo/general
