What modules should be included in generated JavaDocs ? Re: Tuscany JavaDocs Refresh

[Luciano Resende <lu...@gmail.com>]

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



-- 
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/

Re: What modules should be included in generated JavaDocs ? Re: Tuscany JavaDocs Refresh

[Dan Becker <da...@gmail.com>]

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