harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Morozova, Nadezhda" <nadezhda.moroz...@intel.com>
Subject RE: [doc] No Doxygen reference for code :(
Date Tue, 31 Oct 2006 18:02:12 GMT
Alexei,

Thanks for meaningful and numerous questions, Alexei. I have thought of
some of these, but you give it a systematic touch :) 
Others' opinions are welcome, mine in below - marked with [NM]. 

Related question: do we want to have some version of API doc on the site
now? I've experimented with building docs, and could produce a working
bundle. We can work to enable the build create API docs locally in
parallel with that. 

PS: Geir, there's a specific question for you below.

Thank you, 
Nadya Morozova
 

-----Original Message-----
From: Fedotov, Alexei A [mailto:alexei.a.fedotov@intel.com] 
Sent: Tuesday, October 31, 2006 7:49 PM
To: harmony-dev@incubator.apache.org
Subject: RE: [doc] No Doxygen reference for code :(

Nadya, All,

Suggestion to generate Doxygen from DRLVM code sounds very interesting.
I posted a quick solution for Linux to
http://issues.apache.org/jira/browse/HARMONY-2024

[NM] great news, I'll see if I can do smth similar for Windows.

If you want to have this integrated into build.xml, it would be great to
define a correct scope. Could you please give more details what do you
expect from the documentation build file? 
[NM] I'd give it a try. Please don't expect me to write a design doc for
you

A volunteer can try doing some things important for you first, and then
add new features gradually.
[NM] yeah, I like the idea of a gradual step-by-step process.

 * Should doxygen build documentation for inter-component interfaces?
[NM] sure, and I guess it's the better-documented part ;)

 * What are components? I assume vm, jit, gc are out of the question. Is
am execution manager or an interpreter a separate component?
[NM] see dev guide; we've thought components roughly match to top-level
folders:  EM, Interpreter, TM are all components. Not sure what to do
with the three GCs now, though.

 * Should doxygen build documentation for each component like vm, jit,
interpreter, gc?
[NM] It's my dream and very convenient. Getting Doxygen to run for
half-hour and get hung doesn't seem an attractive prospect. However, I
guess we can get some primitive build as a start and add
component-specific build targets later. For me, an ideal list of targets
for Doxygen would be something like:
<all> - all headers for DRLVM/classlib (one of two, not both in one
bundle)
<inter-component> - headers in include/ folder basically. Do we have any
high-level interfaces in other places? This could show the "big picture"
and somehow map to the arch description.
<component> - headers for the component name specified.
We might concentrate on the first two now for simplicity and smaller
scope. 

 * Should we put documentation into doc/<component>_doc dirs as class
library code does?
[NM] this is a complex issue. I know Geir has wanted to add website to
the snapshot. *Geir*, could you express your view on where to place
docs? I guess separating "normal" docs and "autogenerated" docs would be
good, like the /doc/ folder for all files, with /doc/Doxygen/ subfolder
for API reference. When we are ready to build component-specific
reference, /doc/Doxygen/ can have subfolders for each.
 
 * Should we use the same formatting as a class library documentation?
[NM] why not? as I've noticed, default formatting is ok, but there are
many options you can enable/disable, e.g. diagram for class hierarchy.

 * We don't need to process .cpp files in DRLVM source tree, do we?
[NM] no, I guess not. A developer that needs explanation in .cpp would
rather look into the code, I guess.

 * Would each of these choices (inter-component documentation, component
interface documentation) be a separate configuration? If yes, should we
put each result into the separate directory?
 * Should doxygen process .java files in DRLVM source tree? 
 * Should the doxygen documentation be integrated with class library
documentation?
[NM] I hope we can have two different bundles. Otherwise, it'd take our
poor Doxygen a day to compile the docs :) we can cross-reference the two
index.html files. 
Can you estimate, how often you'd want to link from a vm header
description into classlib? 
 
 * Do you expect to have inheritance diagrams? 
[NM] I don't know. From what I see, you don't have complex inheritance
that needs a diagram too often. A 2-3 level list would often be enough.
What do you say?     
* Do we need to download Graphviz, or should we expect it preinstalled? 
[NM] which is simpler? I guess a person that wants to build the doc
suspects that the parsing lib is needed. 

 * A related question is how many platforms should we support. For
example, should I add downloading and compilation of Graphviz for my
SuSE Linux? 
[NM] oh well, I don't know. Perhaps, we can have a README or some other
file that explains what to do to build docs successfully? 

 * Should we have different documentation for Windows and Linux?
[NM] would resulting docs be different or the same? 

 * If something is optional for now, what should be added in future?
[NM] I don't know - it's the future!
 
 * Is there any choice for user to affect resulting documentation?
[NM] I don't have a strong opinion about it, but Doxygen's main idea is
to get docs straight from code. So any change to doxygen's input should
probably be a patch in JIRA. We've had such patches before. 

With best regards,
Alexei Fedotov,
Intel Java & XML Engineering

>-----Original Message-----
>From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
>Sent: Tuesday, October 31, 2006 4:34 PM
>To: harmony-dev@incubator.apache.org
>Subject: [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.m
b
>ox/%3c591B455B-186D-43B4-8F9D-D5A0EA52A38D@pobox.com%3e
>
>
>
>Thanks,
>
>Nadya Morozova

Mime
View raw message