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