Javadoc for specifications and implementation

[Mark Brouwer <ma...@cheiron.org>]

What is the policy at Apache for hosting the generated javadoc for what
we call specifications and implementations, as is currently done by Sun
at e.g. http://java.sun.com/products/jini/2.1/doc/api/

All projects I checked (which was just a sample) have no online Javadoc
and from the past I can recall some deferred to other parties for
hosting the Javadoc.

My personal opinion is that I would like to have the Javadoc online for
the main branch (I believe you call it the trunk) that reflect the
nightly builds as well for every latest release, all in a predictable place.

Not only is this convenient to point to in discussions and helping out
people, it is also essential for those that like to link against these
when generating their own Javadoc.

BTW for the Sun people, what will happen with the current hosting of
specifications, etc. at http://java.sun.com/products/jini?
-- 
Mark

Re: Javadoc for specifications and implementation

[Craig L Russell <Cr...@Sun.COM>]

On Jan 3, 2007, at 4:50 AM, Geir Magnusson Jr. wrote:

>
> On Jan 3, 2007, at 3:37 AM, Mark Brouwer wrote:
>
>> What is the policy at Apache for hosting the generated javadoc for  
>> what
>> we call specifications and implementations, as is currently done  
>> by Sun
>> at e.g. http://java.sun.com/products/jini/2.1/doc/api/
>>
>> All projects I checked (which was just a sample) have no online  
>> Javadoc
>> and from the past I can recall some deferred to other parties for
>> hosting the Javadoc.
>
> In my experience, we put the Javadoc right on the website.  Now,  
> this is stuff I didn't check in, but just generated and "hung" on  
> the website at a designated spot.
>
> But it's the javadoc generated from the project source, not the  
> spec javadoc from elsewhere.
>
>>
>> My personal opinion is that I would like to have the Javadoc  
>> online for
>> the main branch (I believe you call it the trunk) that reflect the
>> nightly builds as well for every latest release, all in a  
>> predictable place.
>>
>> Not only is this convenient to point to in discussions and helping  
>> out
>> people, it is also essential for those that like to link against  
>> these
>> when generating their own Javadoc.
>
> Ok.  I think the nightly is excessive, but I don't really care  
> either way :)

I think it's useful to have "the latest" whether that's the result of  
a nightly or whatever, on the main web site.

It's also useful to have a downloadable version of the entire  
javadoc. This is an easy way to get the whole thing to review  
offline, whereas the html version can be used as a permlink. See  
http://db.apache.org/jdo/javadoc.html for an example. I don't claim  
it's perfect (it isn't automatically built) but it may give some ideas.

Craig

>
>>
>> BTW for the Sun people, what will happen with the current hosting of
>> specifications, etc. at http://java.sun.com/products/jini?
>> -- 
>> Mark
>

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!

Re: Javadoc for specifications and implementation

["Geir Magnusson Jr." <ge...@pobox.com>]

On Jan 3, 2007, at 3:37 AM, Mark Brouwer wrote:

> What is the policy at Apache for hosting the generated javadoc for  
> what
> we call specifications and implementations, as is currently done by  
> Sun
> at e.g. http://java.sun.com/products/jini/2.1/doc/api/
>
> All projects I checked (which was just a sample) have no online  
> Javadoc
> and from the past I can recall some deferred to other parties for
> hosting the Javadoc.

In my experience, we put the Javadoc right on the website.  Now, this  
is stuff I didn't check in, but just generated and "hung" on the  
website at a designated spot.

But it's the javadoc generated from the project source, not the spec  
javadoc from elsewhere.

>
> My personal opinion is that I would like to have the Javadoc online  
> for
> the main branch (I believe you call it the trunk) that reflect the
> nightly builds as well for every latest release, all in a  
> predictable place.
>
> Not only is this convenient to point to in discussions and helping out
> people, it is also essential for those that like to link against these
> when generating their own Javadoc.

Ok.  I think the nightly is excessive, but I don't really care either  
way :)

>
> BTW for the Sun people, what will happen with the current hosting of
> specifications, etc. at http://java.sun.com/products/jini?
> -- 
> Mark

Re: Javadoc for specifications and implementation

["Geir Magnusson Jr." <ge...@pobox.com>]

On Jan 3, 2007, at 4:03 AM, Mark Brouwer wrote:

> Gianugo Rabellino wrote:
>> On 1/3/07, Mark Brouwer <ma...@cheiron.org> wrote:
>>> What is the policy at Apache for hosting the generated javadoc  
>>> for what
>>> we call specifications and implementations, as is currently done  
>>> by Sun
>>> at e.g. http://java.sun.com/products/jini/2.1/doc/api/
>> Generally speaking, a lot of projects host the javadocs as part of  
>> the
>> site. See:
>> http://jakarta.apache.org/slide/javadoc/index.html
>> http://jackrabbit.apache.org/api-1/index.html
>> ... and a lot more.
>
> Thanks for pointing me out Gianugo, I always tend to check the wrong
> projects it seems :-(
>
>>> My personal opinion is that I would like to have the Javadoc  
>>> online for
>>> the main branch (I believe you call it the trunk) that reflect the
>>> nightly builds as well for every latest release, all in a  
>>> predictable place.
>> Makes sense, and I see no problem with it.
>
> So in general there are no restrictions with the documentation
> generation and serving them through apache.org.

As long as it's based on code in the apache repo, no.

geir

> -- 
> Mark

Re: Javadoc for specifications and implementation

[Mark Brouwer <ma...@cheiron.org>]

Gianugo Rabellino wrote:
> On 1/3/07, Mark Brouwer <ma...@cheiron.org> wrote:
>> What is the policy at Apache for hosting the generated javadoc for what
>> we call specifications and implementations, as is currently done by Sun
>> at e.g. http://java.sun.com/products/jini/2.1/doc/api/
> 
> Generally speaking, a lot of projects host the javadocs as part of the
> site. See:
> 
> http://jakarta.apache.org/slide/javadoc/index.html
> http://jackrabbit.apache.org/api-1/index.html
> 
> ... and a lot more.

Thanks for pointing me out Gianugo, I always tend to check the wrong
projects it seems :-(

>> My personal opinion is that I would like to have the Javadoc online for
>> the main branch (I believe you call it the trunk) that reflect the
>> nightly builds as well for every latest release, all in a predictable 
>> place.
> 
> Makes sense, and I see no problem with it.

So in general there are no restrictions with the documentation
generation and serving them through apache.org.
-- 
Mark

Re: Javadoc for specifications and implementation

[Gianugo Rabellino <gi...@apache.org>]

On 1/3/07, Mark Brouwer <ma...@cheiron.org> wrote:
> What is the policy at Apache for hosting the generated javadoc for what
> we call specifications and implementations, as is currently done by Sun
> at e.g. http://java.sun.com/products/jini/2.1/doc/api/

Generally speaking, a lot of projects host the javadocs as part of the
site. See:

http://jakarta.apache.org/slide/javadoc/index.html
http://jackrabbit.apache.org/api-1/index.html

... and a lot more.

> My personal opinion is that I would like to have the Javadoc online for
> the main branch (I believe you call it the trunk) that reflect the
> nightly builds as well for every latest release, all in a predictable place.

Makes sense, and I see no problem with it.

-- 
Gianugo Rabellino
Sourcesense, making sense of Open Source: http://www.sourcesense.com
Orixo, the XML business alliance: http://www.orixo.com
(blogging at http://www.rabellino.it/blog/)

Re: Javadoc for specifications and implementation

[Mark Brouwer <ma...@cheiron.org>]

Jim Hurley wrote:
> On Jan 3, 2007, at 3:37 AM, Mark Brouwer wrote:
>> :
>> BTW for the Sun people, what will happen with the current hosting of
>> specifications, etc. at http://java.sun.com/products/jini?
> 
> We haven't discussed it intently, but my expectation was
> that we would keep them there while they were still
> useful/helpful.

I would be grateful if that would be the case.
-- 
Mark

Re: Javadoc for specifications and implementation

[Jim Hurley <Ji...@Sun.COM>]

On Jan 3, 2007, at 3:37 AM, Mark Brouwer wrote:
> :
> BTW for the Sun people, what will happen with the current hosting of
> specifications, etc. at http://java.sun.com/products/jini?

We haven't discussed it intently, but my expectation was
that we would keep them there while they were still
useful/helpful.

-Jim