harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Fedotov, Alexei A" <alexei.a.fedo...@intel.com>
Subject RE: [doc] No Doxygen reference for code :(
Date Wed, 01 Nov 2006 16:44:32 GMT
Nadya,

Sorry, I supposed to say the same thing. By requirement engineering I
meant a discussion of requirements.

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

>-----Original Message-----
>From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
>Sent: Wednesday, November 01, 2006 5:09 PM
>To: harmony-dev@incubator.apache.org
>Subject: RE: [doc] No Doxygen reference for code :(
>
>Alexei,
>One note: I'm *not* writing requirements for engineering on the doc
>build system. I'm just sharing my thoughts on an issue that interests
>me. Discussion is welcome. Please don't consider my ideas as "the way
it
>should be".
>
>Thank you,
>Nadya Morozova
>
>
>-----Original Message-----
>From: Fedotov, Alexei A [mailto:alexei.a.fedotov@intel.com]
>Sent: Wednesday, November 01, 2006 4:52 PM
>To: harmony-dev@incubator.apache.org
>Subject: RE: [doc] No Doxygen reference for code :(
>
>Nadya,
>
>Thanks for answers. You have a nice approach to the requirement
>engineering for the documentation build system. It would be great if
you
>also add priorities for your requirements.
>
>Looking into your original list of requirements, I've noticed I haven't
>addressed the second one:
>>2. Ability to see docs on the website
>
>Yesterday I'd added an archive with documentation to HARMONY-2024
>http://issues.apache.org/jira/browse/HARMONY-2024, so committers could
>now put documentation to the web site and everyone could contribute to
>the documentation quality.
>
>With best regards,
>Alexei Fedotov,
>Intel Java & XML Engineering
>
>>-----Original Message-----
>>From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
>>Sent: Tuesday, October 31, 2006 9:02 PM
>>To: harmony-dev@incubator.apache.org
>>Subject: RE: [doc] No Doxygen reference for code :(
>>
>>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