Both good questions.
1) Definitely SPIs should have well maintained JavaDocs. I would prefer
in addition to the code we have a more readable and well maintained
JavaDoc. So these new JavaDocs should help there, bringing our version
0.9 to 1.4.
2) It is true that many of the impl classes and various infrastructure
classes are more likely to change. I think this issue pertains also
when people mark classes public (rather than protected or private) or
rewrite an impl class and add or subtract new methods. This is not just
a JavaDoc issue, but a change issue. For any class we make public, I
would like to see some JavaDocs on those classes, regardless if they are
a rock solid SPI or the simplest little util class. If they change we
should make sure we tag APIs properly with @since, @deprecated, and
@link tags to help users understand and deal with the change.
Luciano Resende wrote:
In the past, we had generated JavaDocs for what we were considering
somewhat stable SPIs.
I noticed that you have generated JavaDocs for all our source, and I
have two concerns with that :
1) We usually only do a good/ok job on creating/maintaining
javadocs for SPIs.
2) What are the user implications of generating javadocs on things
that are in constant change ?
Are they going to assume these are somewhat stable SPIs ?
Thoughts ?
[1] http://people.apache.org/~beckerdo/tuscany/javadoc-sca-1.4/
On Wed, Jan 28, 2009 at 8:38 AM, Dan Becker <dan.o.bec...@gmail.com> wrote:
I made some JavaDocs for Tuscany 1.4. If you would like to have a look, I
placed it on my Apache personal space here [1], and once I get a few
comments or change requests, I will check it in.
Please let me know if you would like to change the style, add any titles or
footers, or remove any packages.
Here is the basic method I used to generate the docs:
1) Get a directory list of all src directories under tuscany modules.
2) Grep only for paths that end in src/main/java.
3) Generate javadoc with
javadoc -d html -sourcepath $(SRCDIRS) -subpackages org.apache.tuscany
(Note that SRCDIRS contains a list of 133 directories. It took my laptop
over 7 hours to generate all the files. Maybe next time I will copy all the
src trees to one location to save time. The zip file of the docs is 5.8 MB.)
[1] http://people.apache.org/~beckerdo/tuscany/
Luciano Resende wrote:
When we last looked at this, there was an issue around grouping the
java docs produced by multiple modules, and we had to do it manually.
I was thinking about this for 2.x, and one idea would be to use the
same technique we use to produce a "all jar", where we group multiple
modules, and then produce the javadoc from that temporary grouped set
of modules ?
On Tue, Jan 27, 2009 at 8:26 AM, Dan Becker <dan.o.bec...@gmail.com>
wrote:
I noticed an older Tuscany Jira requesting an update on the Tuscany
JavaDocs
[1]. It appears the last public Tuscany JavaDoc we release is at the 0.9
level. I intend on resolving the Jira and making a 1.4 level JavaDoc and
publishing at http://tuscany.apache.org/doc/javadoc/. Any words of wisdom
or
other helpful hints before I jump?
[1] http://issues.apache.org/jira/browse/TUSCANY-2485
--
--
Thanks, Dan Becker
