You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@jakarta.apache.org by Henri Yandell <ba...@generationjava.com> on 2005/03/16 06:49:08 UTC
Javadoc management
Interested in finding out if anyone else thinks this would be a good idea.
Rather than have each subproject managing their release javadocs
separately, I think it would be good if we treated the javadoc more like
the releases. Located in a central location, perhaps mirrored, all
versions available and perhaps with additional tools like ashkelon or
multidoc to bring them together.
Subprojects would still be hosting their latest cvs head javadocs
internally, but they would deploy a versioned javadoc as a part of
releasing, and we wouldn't end up with the issue where users cannot view
the latest released javadoc due to a site rebuild etc.
Javadoc seems less important for some projects, Taglibs and Tomcat leap to
mind, so it may not apply for all (though seeing a tag doc in javadoc
style would rock).
Anyway. Looking for community interest. If there, I'd make it my 2005 Q2
task, probably along with trying to hassle on LGPL stuff again.
As it's my current weapon of choice, I'd probably end up with an xml/xslt
solution much like the download stuff, so feel free to point out that that
wasy crap.
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by Joe Germuska <Jo...@Germuska.com>.
At 12:49 AM -0500 3/16/05, Henri Yandell wrote:
>(though seeing a tag doc in javadoc style would rock).
Have you seen
https://taglibrarydoc.dev.java.net/
It is used, for example, to generate this:
http://java.sun.com/products/jsp/jstl/1.1/docs/tlddocs/
There's a Maven plugin which is savvy about this tool, but I haven't used it:
http://maven-taglib.sourceforge.net/index.html
Joe
--
Joe Germuska
Joe@Germuska.com
http://blog.germuska.com
"Narrow minds are weapons made for mass destruction" -The Ex
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by Henri Yandell <ba...@generationjava.com>.
On Tue, 15 Mar 2005, Martin Cooper wrote:
> On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell
> <ba...@generationjava.com> wrote:
>>
>> Interested in finding out if anyone else thinks this would be a good idea.
>>
>> Rather than have each subproject managing their release javadocs
>> separately, I think it would be good if we treated the javadoc more like
>> the releases. Located in a central location, perhaps mirrored, all
>> versions available and perhaps with additional tools like ashkelon or
>> multidoc to bring them together.
>
> Sounds good to me (assuming you mean all *released* versions
> available). On download pages, we could have binaries, sources and
> javadocs, with options for javadocs being download or view online (a
> bit like Sun's download pages). We might not need to mirror right away
> - we could wait to see how much this gets used.
Yep. Unsure if the download page would be the best place for the view
online option though.
> I'm not familiar with ashkelon or multidoc. What would they bring to the party?
Ashkelon is an alternative to javadoc really. You load the javadoc into a
database and it gives you a searchable system and a slightly more
descriptive version of javadoc. I've a basic version running at:
http://issues.osjava.org/ashkelon/apis.do
while http://www.jdocs.com/ have a more customised version. It requires a
db and a tomcat server.
Multidocs is a hack of mine. It scrapes from various existing javadoc urls
and builds a wrapper around them:
http://www.apache.org/~bayard/multidoc/commons-multidoc/
I also had it doing src xref, test coverage etc.
Low cost, but all it really adds is a nicer way for the user to find the
javadoc they want.
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by Martin Cooper <mf...@gmail.com>.
On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell
<ba...@generationjava.com> wrote:
>
> Interested in finding out if anyone else thinks this would be a good idea.
>
> Rather than have each subproject managing their release javadocs
> separately, I think it would be good if we treated the javadoc more like
> the releases. Located in a central location, perhaps mirrored, all
> versions available and perhaps with additional tools like ashkelon or
> multidoc to bring them together.
Sounds good to me (assuming you mean all *released* versions
available). On download pages, we could have binaries, sources and
javadocs, with options for javadocs being download or view online (a
bit like Sun's download pages). We might not need to mirror right away
- we could wait to see how much this gets used.
I'm not familiar with ashkelon or multidoc. What would they bring to the party?
--
Martin Cooper
> Subprojects would still be hosting their latest cvs head javadocs
> internally, but they would deploy a versioned javadoc as a part of
> releasing, and we wouldn't end up with the issue where users cannot view
> the latest released javadoc due to a site rebuild etc.
>
> Javadoc seems less important for some projects, Taglibs and Tomcat leap to
> mind, so it may not apply for all (though seeing a tag doc in javadoc
> style would rock).
>
> Anyway. Looking for community interest. If there, I'd make it my 2005 Q2
> task, probably along with trying to hassle on LGPL stuff again.
>
> As it's my current weapon of choice, I'd probably end up with an xml/xslt
> solution much like the download stuff, so feel free to point out that that
> wasy crap.
>
> Hen
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by Henri Yandell <ba...@generationjava.com>.
On Fri, 18 Mar 2005, J Aaron Farr wrote:
> On Fri, 18 Mar 2005 12:22:35 -0500 (EST), Henri Yandell
> <ba...@generationjava.com> wrote:
>
>> Gump is another possibility. I noticed the other day that they have
>> javadoc in the gump.xml.
>
> Trouble with having this Gump driven is that Gump is all about
> building the latest snapshot, not about building a specific release
> version. Moreover, the builds have a pretty high failure rate.
Right.
> But that does bring up a good question about where the javadocs come
> from. Would this site/tool generate them directly from the source or
> would projects have to supply the javadocs? If projects have to
> supply the pre-generated Javadocs then we could just require they are
> distributed via the mirrors and this site could pick them up from
> there.
First I was thinking that it would be this way. We'd effectively get a
working prototype of how things can look and user's can find javadocs a
lot more easily, without us having to try and guess what a more complex
system would look like.
The only pain created would be as an addition to release management, which
is annoying as release management is already a slow enough process, but
we're going to be tying this to releases no matter what happens anyway.
> However, if the site generates the javadocs then we'd have a
> lot more control over how they look and how they're linked.
Then I would see us discussing this. It could involve loading into
ashkelon etc. We'd have a basic working system to use as a foundation to
all the ideas.
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by J Aaron Farr <ja...@gmail.com>.
On Fri, 18 Mar 2005 12:22:35 -0500 (EST), Henri Yandell
<ba...@generationjava.com> wrote:
> Gump is another possibility. I noticed the other day that they have
> javadoc in the gump.xml.
Trouble with having this Gump driven is that Gump is all about
building the latest snapshot, not about building a specific release
version. Moreover, the builds have a pretty high failure rate.
But that does bring up a good question about where the javadocs come
from. Would this site/tool generate them directly from the source or
would projects have to supply the javadocs? If projects have to
supply the pre-generated Javadocs then we could just require they are
distributed via the mirrors and this site could pick them up from
there. However, if the site generates the javadocs then we'd have a
lot more control over how they look and how they're linked.
--
jaaron
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by Jeff Martin <je...@mkodo.com>.
My involvement was with what has now become tucked away in a zip file
called alexandria-legacy. At this time Alexandria was an ant build
script with some ant extensions. Most of these are now part of ant.
Alexandra's main goal was to allow people to access javadoc and xrefed
source code. The build and testing stuff was just a logical extension of
having a system which could automatically checkout code. Gump now
handles this much better.
Anyway just trying to bring people's attention to an existing solution
rather than trying to start everything from scratch.
On Fri, 2005-03-18 at 12:22 -0500, Henri Yandell wrote:
> My negatives for Alexandria:
>
> * Seems large and yet dead
> * Has lofty goals, whereas the below is very basic
>
> Gump is another possibility. I noticed the other day that they have
> javadoc in the gump.xml.
>
> My argument for the below over trying to do things with gump is that it is
> simple to get running and find out what we actually want. Once we have
> that, we can try to drive gump/alexandria/something-else.
>
> Hen
>
> On Fri, 18 Mar 2005, Jeff Martin wrote:
>
> > Just wondering if anyone had looked at Alexandria.
> > http://jakarta.apache.org/alexandria/legacy/
> >
> > On Fri, 2005-03-18 at 00:31 -0500, Henri Yandell wrote:
> >>
> >> On Thu, 17 Mar 2005, J Aaron Farr wrote:
> >>
> >>> On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell
> >>> <ba...@generationjava.com> wrote:
> >>>>
> >>>> Interested in finding out if anyone else thinks this would be a good idea.
> >>>>
> >>>> Rather than have each subproject managing their release javadocs
> >>>> separately, I think it would be good if we treated the javadoc more like
> >>>> the releases. Located in a central location, perhaps mirrored, all
> >>>> versions available and perhaps with additional tools like ashkelon or
> >>>> multidoc to bring them together.
> >>>
> >>> I guess I'm hoping for something like:
> >>>
> >>> http://api.apache.org/$group/$artifact/$version/
> >>
> >> Sounds good, though possibly:
> >>
> >> http://jakarta.apache.org/api/$subproject/$artifact/$version/
> >>
> >> to get a prototype up and running.
> >>
> >>> with features like
> >>>
> >>> * download the javadocs
> >>
> >> +1. Unsure how this would balance with the download pages.
> >>
> >>> * search javadocs
> >>
> >> +1 long-term.
> >>
> >>> * have javadocs linked to source reference (so maybe have an 'api'
> >>> and a 'src' directory)
> >>
> >> Not hugely essential I think.
> >>
> >>> * have javadocs linked to each other
> >>
> >> Would be very nice, but seems like a battle. We wouldn't want to rebuild
> >> the javadoc as part of this, and might not be easy to find a way to munge
> >> existing javadoc to point to each other. Also means dependency knowledge,
> >> which version of Collections did this BeanUtils use.
> >>
> >>> * include test and taglib javadocs
> >>
> >> +1 on taglibs. Test ones are less essential to start with I think.
> >>
> >>> Plus it's got to be pretty simple to set this up or for projects to
> >>> contribute to it.
> >>
> >> To start with, I'm generally thinking of a defined file structure in which
> >> unzipped javadocs appear, a location for downloadable javadoc to be and a
> >> front end to make it easy to get to the relevant javadoc.
> >>
> >> A release would involve putting the new javadoc in place, adding it to the
> >> front-end (hopefully in a one-line kind of way) and then creating a
> >> downloadable zip.
> >>
> >> Initial plan would be to propose a structure for the repository (I like
> >> yours), go extract a lot of javadocs from our downloads to seed the
> >> repository, and come up with a simple-front-end to let people use them.
> >>
> >> An important requirement will be the need for a subproject/group to be
> >> able to link to a page that defines their javadoc, rather than at the top
> >> level.
> >>
> >> Hen
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> >> For additional commands, e-mail: general-help@jakarta.apache.org
> > --
> > Jeff Martin
> >
> > Memetic Engineer
> >
> > http://www.custommonkey.org/
> >
> >
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: general-help@jakarta.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
--
jeff martin
information technologist
mkodo limited
mobile: 44 (0) 78 55 478 331
phone: 44 (0) 20 77 29 45 45
email: jeff.martin@mkodo.com
www.mkodo.com
73 Leonard St, London, EC2A 4QS. U.K
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by Henri Yandell <ba...@generationjava.com>.
My negatives for Alexandria:
* Seems large and yet dead
* Has lofty goals, whereas the below is very basic
Gump is another possibility. I noticed the other day that they have
javadoc in the gump.xml.
My argument for the below over trying to do things with gump is that it is
simple to get running and find out what we actually want. Once we have
that, we can try to drive gump/alexandria/something-else.
Hen
On Fri, 18 Mar 2005, Jeff Martin wrote:
> Just wondering if anyone had looked at Alexandria.
> http://jakarta.apache.org/alexandria/legacy/
>
> On Fri, 2005-03-18 at 00:31 -0500, Henri Yandell wrote:
>>
>> On Thu, 17 Mar 2005, J Aaron Farr wrote:
>>
>>> On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell
>>> <ba...@generationjava.com> wrote:
>>>>
>>>> Interested in finding out if anyone else thinks this would be a good idea.
>>>>
>>>> Rather than have each subproject managing their release javadocs
>>>> separately, I think it would be good if we treated the javadoc more like
>>>> the releases. Located in a central location, perhaps mirrored, all
>>>> versions available and perhaps with additional tools like ashkelon or
>>>> multidoc to bring them together.
>>>
>>> I guess I'm hoping for something like:
>>>
>>> http://api.apache.org/$group/$artifact/$version/
>>
>> Sounds good, though possibly:
>>
>> http://jakarta.apache.org/api/$subproject/$artifact/$version/
>>
>> to get a prototype up and running.
>>
>>> with features like
>>>
>>> * download the javadocs
>>
>> +1. Unsure how this would balance with the download pages.
>>
>>> * search javadocs
>>
>> +1 long-term.
>>
>>> * have javadocs linked to source reference (so maybe have an 'api'
>>> and a 'src' directory)
>>
>> Not hugely essential I think.
>>
>>> * have javadocs linked to each other
>>
>> Would be very nice, but seems like a battle. We wouldn't want to rebuild
>> the javadoc as part of this, and might not be easy to find a way to munge
>> existing javadoc to point to each other. Also means dependency knowledge,
>> which version of Collections did this BeanUtils use.
>>
>>> * include test and taglib javadocs
>>
>> +1 on taglibs. Test ones are less essential to start with I think.
>>
>>> Plus it's got to be pretty simple to set this up or for projects to
>>> contribute to it.
>>
>> To start with, I'm generally thinking of a defined file structure in which
>> unzipped javadocs appear, a location for downloadable javadoc to be and a
>> front end to make it easy to get to the relevant javadoc.
>>
>> A release would involve putting the new javadoc in place, adding it to the
>> front-end (hopefully in a one-line kind of way) and then creating a
>> downloadable zip.
>>
>> Initial plan would be to propose a structure for the repository (I like
>> yours), go extract a lot of javadocs from our downloads to seed the
>> repository, and come up with a simple-front-end to let people use them.
>>
>> An important requirement will be the need for a subproject/group to be
>> able to link to a page that defines their javadoc, rather than at the top
>> level.
>>
>> Hen
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
>> For additional commands, e-mail: general-help@jakarta.apache.org
> --
> Jeff Martin
>
> Memetic Engineer
>
> http://www.custommonkey.org/
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by Jeff Martin <je...@custommonkey.org>.
Just wondering if anyone had looked at Alexandria.
http://jakarta.apache.org/alexandria/legacy/
On Fri, 2005-03-18 at 00:31 -0500, Henri Yandell wrote:
>
> On Thu, 17 Mar 2005, J Aaron Farr wrote:
>
> > On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell
> > <ba...@generationjava.com> wrote:
> >>
> >> Interested in finding out if anyone else thinks this would be a good idea.
> >>
> >> Rather than have each subproject managing their release javadocs
> >> separately, I think it would be good if we treated the javadoc more like
> >> the releases. Located in a central location, perhaps mirrored, all
> >> versions available and perhaps with additional tools like ashkelon or
> >> multidoc to bring them together.
> >
> > I guess I'm hoping for something like:
> >
> > http://api.apache.org/$group/$artifact/$version/
>
> Sounds good, though possibly:
>
> http://jakarta.apache.org/api/$subproject/$artifact/$version/
>
> to get a prototype up and running.
>
> > with features like
> >
> > * download the javadocs
>
> +1. Unsure how this would balance with the download pages.
>
> > * search javadocs
>
> +1 long-term.
>
> > * have javadocs linked to source reference (so maybe have an 'api'
> > and a 'src' directory)
>
> Not hugely essential I think.
>
> > * have javadocs linked to each other
>
> Would be very nice, but seems like a battle. We wouldn't want to rebuild
> the javadoc as part of this, and might not be easy to find a way to munge
> existing javadoc to point to each other. Also means dependency knowledge,
> which version of Collections did this BeanUtils use.
>
> > * include test and taglib javadocs
>
> +1 on taglibs. Test ones are less essential to start with I think.
>
> > Plus it's got to be pretty simple to set this up or for projects to
> > contribute to it.
>
> To start with, I'm generally thinking of a defined file structure in which
> unzipped javadocs appear, a location for downloadable javadoc to be and a
> front end to make it easy to get to the relevant javadoc.
>
> A release would involve putting the new javadoc in place, adding it to the
> front-end (hopefully in a one-line kind of way) and then creating a
> downloadable zip.
>
> Initial plan would be to propose a structure for the repository (I like
> yours), go extract a lot of javadocs from our downloads to seed the
> repository, and come up with a simple-front-end to let people use them.
>
> An important requirement will be the need for a subproject/group to be
> able to link to a page that defines their javadoc, rather than at the top
> level.
>
> Hen
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
--
Jeff Martin
Memetic Engineer
http://www.custommonkey.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by Henri Yandell <ba...@generationjava.com>.
On Thu, 17 Mar 2005, J Aaron Farr wrote:
> On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell
> <ba...@generationjava.com> wrote:
>>
>> Interested in finding out if anyone else thinks this would be a good idea.
>>
>> Rather than have each subproject managing their release javadocs
>> separately, I think it would be good if we treated the javadoc more like
>> the releases. Located in a central location, perhaps mirrored, all
>> versions available and perhaps with additional tools like ashkelon or
>> multidoc to bring them together.
>
> I guess I'm hoping for something like:
>
> http://api.apache.org/$group/$artifact/$version/
Sounds good, though possibly:
http://jakarta.apache.org/api/$subproject/$artifact/$version/
to get a prototype up and running.
> with features like
>
> * download the javadocs
+1. Unsure how this would balance with the download pages.
> * search javadocs
+1 long-term.
> * have javadocs linked to source reference (so maybe have an 'api'
> and a 'src' directory)
Not hugely essential I think.
> * have javadocs linked to each other
Would be very nice, but seems like a battle. We wouldn't want to rebuild
the javadoc as part of this, and might not be easy to find a way to munge
existing javadoc to point to each other. Also means dependency knowledge,
which version of Collections did this BeanUtils use.
> * include test and taglib javadocs
+1 on taglibs. Test ones are less essential to start with I think.
> Plus it's got to be pretty simple to set this up or for projects to
> contribute to it.
To start with, I'm generally thinking of a defined file structure in which
unzipped javadocs appear, a location for downloadable javadoc to be and a
front end to make it easy to get to the relevant javadoc.
A release would involve putting the new javadoc in place, adding it to the
front-end (hopefully in a one-line kind of way) and then creating a
downloadable zip.
Initial plan would be to propose a structure for the repository (I like
yours), go extract a lot of javadocs from our downloads to seed the
repository, and come up with a simple-front-end to let people use them.
An important requirement will be the need for a subproject/group to be
able to link to a page that defines their javadoc, rather than at the top
level.
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Javadoc management
Posted by J Aaron Farr <ja...@gmail.com>.
On Wed, 16 Mar 2005 00:49:08 -0500 (EST), Henri Yandell
<ba...@generationjava.com> wrote:
>
> Interested in finding out if anyone else thinks this would be a good idea.
>
> Rather than have each subproject managing their release javadocs
> separately, I think it would be good if we treated the javadoc more like
> the releases. Located in a central location, perhaps mirrored, all
> versions available and perhaps with additional tools like ashkelon or
> multidoc to bring them together.
I guess I'm hoping for something like:
http://api.apache.org/$group/$artifact/$version/
with features like
* download the javadocs
* search javadocs
* have javadocs linked to source reference (so maybe have an 'api'
and a 'src' directory)
* have javadocs linked to each other
* include test and taglib javadocs
Plus it's got to be pretty simple to set this up or for projects to
contribute to it.
I like the idea of including javadocs as part of the release process
and I like the idea of encouraging projects to host the lastest
javadocs on their own site.
--
jaaron
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org