You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@harmony.apache.org by "Morozova, Nadezhda" <na...@intel.com> on 2006/10/31 14:33:51 UTC
[doc] No Doxygen reference for code :(
Hi everyone,
I've noticed that there's no API reference documentation for Harmony
code - generated by Doxygen/Javadoc. I guess many will agree that
having API reference is very useful and convenient.
This issue was discussed a while ago [1] for kernel classes and vmi
interface in classlib. We agreed to store the Doxygen docs on the
website by generating them manually from code and placing there. It
seems that the old version of the docs was removed from SVN but never
made its way to the website, so it's just NOWHERE now :-(. Let's fix it!
AFAIU, we want to have the following:
1. Ability to generate docs locally from source code as part of
build - need to change existing build files or write new ones.
2. Ability to see docs on the website - manually copy a local
bundle of docs to the website and add a link. Geir has been planning to
include the website into the next snapshot; supplying ready reference
with it seem nice.
Volunteers?
I can work on item 2 for sure to get a nice config file and patch the
website to link to our new Doxygen API. Item 1 -fixing the build - might
be more extravagant, so your aid's welcome ;)
[1] mail thread
http://mail-archives.apache.org/mod_mbox/incubator-harmony-dev/200609.mb
ox/%3c591B455B-186D-43B4-8F9D-D5A0EA52A38D@pobox.com%3e
Thanks,
Nadya Morozova
Re: [doc] No Doxygen reference for code :(
Posted by Paulex Yang <pa...@gmail.com>.
Alexey Petrenko wrote:
> I think that we can place the docs here:
> http://incubator.apache.org/harmony/subcomponents/classlibrary/index.html
Yes, that's one of my candidate, another one is here:
standard/site/docs/documentation/documentation.html, because I think it
is also a reasonable idea for the user to go for "documentation" if you
wanna some API explanation. How about we put the API document in each
subcomponents(classlib/drlvm/jchevm), but also add their link in
documentation/documentation.html?
>
> 2006/11/1, Paulex Yang <pa...@gmail.com>:
>> Morozova, Nadezhda wrote:
>> > Hi everyone,
>> >
>> > I've noticed that there's no API reference documentation for Harmony
>> > code - generated by Doxygen/Javadoc. I guess many will agree that
>> > having API reference is very useful and convenient.
>> >
>> >
>> >
>> > This issue was discussed a while ago [1] for kernel classes and vmi
>> > interface in classlib. We agreed to store the Doxygen docs on the
>> > website by generating them manually from code and placing there. It
>> > seems that the old version of the docs was removed from SVN but never
>> > made its way to the website, so it's just NOWHERE now :-(. Let's
>> fix it!
>> >
>> >
>> > AFAIU, we want to have the following:
>> >
>> > 1. Ability to generate docs locally from source code as part of
>> > build - need to change existing build files or write new ones.
>> > 2. Ability to see docs on the website - manually copy a local
>> > bundle of docs to the website and add a link. Geir has been
>> planning to
>> > include the website into the next snapshot; supplying ready reference
>> > with it seem nice.
>> >
>> > Volunteers?
>>
>> > I can work on item 2 for sure to get a nice config file and patch the
>> > website to link to our new Doxygen API. Item 1 -fixing the build -
>> might
>> > be more extravagant, so your aid's welcome ;)
>> >
>> It is me that removed the original document in classlib/trunk/doc as we
>> discussed before, so seems it should be my responsibility to make the
>> work complete:). Sorry for delaying so long. But I still have no strong
>> feelings where to put them in standard/site, any suggestions?
>>
>> You can create all the API document by run "ant" in classlib/trunk/doc,
>> you can get all document created, assuming Doxygen is installed. If you
>> kindly provide the patch, I will look at it and merge it into SVN.
>> >
>> >
>> > [1] mail thread
>> >
>> http://mail-archives.apache.org/mod_mbox/incubator-harmony-dev/200609.mb
>> > ox/%3c591B455B-186D-43B4-8F9D-D5A0EA52A38D@pobox.com%3e
>> >
>> >
>> >
>> > Thanks,
>> >
>> > Nadya Morozova
>> >
>> >
>> >
>>
>>
>> --
>> Paulex Yang
>> China Software Development Lab
>> IBM
>>
>>
>>
>
--
Paulex Yang
China Software Development Lab
IBM
Re: [doc] No Doxygen reference for code :(
Posted by Alexey Petrenko <al...@gmail.com>.
I think that we can place the docs here:
http://incubator.apache.org/harmony/subcomponents/classlibrary/index.html
2006/11/1, Paulex Yang <pa...@gmail.com>:
> Morozova, Nadezhda wrote:
> > Hi everyone,
> >
> > I've noticed that there's no API reference documentation for Harmony
> > code - generated by Doxygen/Javadoc. I guess many will agree that
> > having API reference is very useful and convenient.
> >
> >
> >
> > This issue was discussed a while ago [1] for kernel classes and vmi
> > interface in classlib. We agreed to store the Doxygen docs on the
> > website by generating them manually from code and placing there. It
> > seems that the old version of the docs was removed from SVN but never
> > made its way to the website, so it's just NOWHERE now :-(. Let's fix it!
> >
> >
> > AFAIU, we want to have the following:
> >
> > 1. Ability to generate docs locally from source code as part of
> > build - need to change existing build files or write new ones.
> > 2. Ability to see docs on the website - manually copy a local
> > bundle of docs to the website and add a link. Geir has been planning to
> > include the website into the next snapshot; supplying ready reference
> > with it seem nice.
> >
> > Volunteers?
>
> > I can work on item 2 for sure to get a nice config file and patch the
> > website to link to our new Doxygen API. Item 1 -fixing the build - might
> > be more extravagant, so your aid's welcome ;)
> >
> It is me that removed the original document in classlib/trunk/doc as we
> discussed before, so seems it should be my responsibility to make the
> work complete:). Sorry for delaying so long. But I still have no strong
> feelings where to put them in standard/site, any suggestions?
>
> You can create all the API document by run "ant" in classlib/trunk/doc,
> you can get all document created, assuming Doxygen is installed. If you
> kindly provide the patch, I will look at it and merge it into SVN.
> >
> >
> > [1] mail thread
> > http://mail-archives.apache.org/mod_mbox/incubator-harmony-dev/200609.mb
> > ox/%3c591B455B-186D-43B4-8F9D-D5A0EA52A38D@pobox.com%3e
> >
> >
> >
> > Thanks,
> >
> > Nadya Morozova
> >
> >
> >
>
>
> --
> Paulex Yang
> China Software Development Lab
> IBM
>
>
>
Re: [doc] No Doxygen reference for code :(
Posted by Paulex Yang <pa...@gmail.com>.
Morozova, Nadezhda wrote:
> Hi everyone,
>
> I've noticed that there's no API reference documentation for Harmony
> code - generated by Doxygen/Javadoc. I guess many will agree that
> having API reference is very useful and convenient.
>
>
>
> This issue was discussed a while ago [1] for kernel classes and vmi
> interface in classlib. We agreed to store the Doxygen docs on the
> website by generating them manually from code and placing there. It
> seems that the old version of the docs was removed from SVN but never
> made its way to the website, so it's just NOWHERE now :-(. Let's fix it!
>
>
> AFAIU, we want to have the following:
>
> 1. Ability to generate docs locally from source code as part of
> build - need to change existing build files or write new ones.
> 2. Ability to see docs on the website - manually copy a local
> bundle of docs to the website and add a link. Geir has been planning to
> include the website into the next snapshot; supplying ready reference
> with it seem nice.
>
> Volunteers?
> I can work on item 2 for sure to get a nice config file and patch the
> website to link to our new Doxygen API. Item 1 -fixing the build - might
> be more extravagant, so your aid's welcome ;)
>
It is me that removed the original document in classlib/trunk/doc as we
discussed before, so seems it should be my responsibility to make the
work complete:). Sorry for delaying so long. But I still have no strong
feelings where to put them in standard/site, any suggestions?
You can create all the API document by run "ant" in classlib/trunk/doc,
you can get all document created, assuming Doxygen is installed. If you
kindly provide the patch, I will look at it and merge it into SVN.
>
>
> [1] mail thread
> http://mail-archives.apache.org/mod_mbox/incubator-harmony-dev/200609.mb
> ox/%3c591B455B-186D-43B4-8F9D-D5A0EA52A38D@pobox.com%3e
>
>
>
> Thanks,
>
> Nadya Morozova
>
>
>
--
Paulex Yang
China Software Development Lab
IBM
Re: [doc] No Doxygen reference for code :(
Posted by Egor Pasko <eg...@gmail.com>.
On the 0x230 day of Apache Harmony Salikh Zakirov wrote:
> Morozova, Nadezhda wrote:
> > I've noticed that there's no API reference documentation for Harmony
> > code - generated by Doxygen/Javadoc. I guess many will agree that
> > having API reference is very useful and convenient.
>
> I've tried to build doxygen documentation for the Thread Manager
> component of the DRLVM (i.e. drlvm/vm/thread/src/*.[ch] +
> drlvm/vm/include/open/*thr*.h).
>
> I needed to have a Doxyfile and fix a couple of warnings along the way,
> please see the patch attached to HARMONY-2351.
>
> However, the generated documentation was of little use to me,
> due to the generated documentation treating all structure members
> as 'typedef's, while in fact they are just regular struct fields.
>
> > 1. Ability to generate docs locally from source code as part of
> > build - need to change existing build files or write new ones.
>
> After adding Doxyfile to drlvm/vm/thread/doc, one can do following:
>
> $ cd drlvm/vm/thread/doc
> $ doxygen
>
> then browse drlvm/vm/thread/doc/html/index.html
>
> > 2. Ability to see docs on the website - manually copy a local
> > bundle of docs to the website and add a link. Geir has been planning to
> > include the website into the next snapshot; supplying ready reference
> > with it seem nice.
>
> Judging from the quality of docs generated from thread manager,
> we should *not* publish it on a web-site.
why? what can make us hide the most part?
we have our sources, ok, not ideally documented, but we will see how
to improve them if they are on the website.
> The only documentation that may be worth linking is intercomponent header files in:
>
> drlvm/vm/include/open/
Why should we carefully select "clean" parts and then "publish" them
as if we were writing a book?
I think, *all code must be documented* more or less. Some more, some less.
Making all the project Doxygen docs visible from the website allows:
* developers to walk through links, view class diagram charts and find
what they want (in latest snapshots)
* beginner developers to see the best-documented top-level docs to
understand the basic architectural conscepts
* all of us to review the documentation *easier*, suggest changes,
document more
aren't my arguments convincing? :)
--
Egor Pasko
Re: [doc] No Doxygen reference for code :(
Posted by Salikh Zakirov <Sa...@Intel.com>.
Morozova, Nadezhda wrote:
> I've noticed that there's no API reference documentation for Harmony
> code - generated by Doxygen/Javadoc. I guess many will agree that
> having API reference is very useful and convenient.
I've tried to build doxygen documentation for the Thread Manager
component of the DRLVM (i.e. drlvm/vm/thread/src/*.[ch] +
drlvm/vm/include/open/*thr*.h).
I needed to have a Doxyfile and fix a couple of warnings along the way,
please see the patch attached to HARMONY-2351.
However, the generated documentation was of little use to me,
due to the generated documentation treating all structure members
as 'typedef's, while in fact they are just regular struct fields.
> 1. Ability to generate docs locally from source code as part of
> build - need to change existing build files or write new ones.
After adding Doxyfile to drlvm/vm/thread/doc, one can do following:
$ cd drlvm/vm/thread/doc
$ doxygen
then browse drlvm/vm/thread/doc/html/index.html
> 2. Ability to see docs on the website - manually copy a local
> bundle of docs to the website and add a link. Geir has been planning to
> include the website into the next snapshot; supplying ready reference
> with it seem nice.
Judging from the quality of docs generated from thread manager,
we should *not* publish it on a web-site.
The only documentation that may be worth linking is intercomponent header files in:
drlvm/vm/include/open/