Hi,
I've tried out the scripts that build Doxygen docs for DRLVM. I like the
resulting input immensely, though further improvements might be required
- will write specific suggestions later.
At this point, my key question is the following: How do we want to
organize our docs? Possible solutions:
- harmony_intf_doc: classlib + drlvm docs, one huge bundle.
Not sure it can work ok or be easy to maintain, but...
- drlvm_intf_doc + classlib_intf_doc: two bundles;
drlvm_intf was submitted by Alexei to the same JIRA - can use as
a starting point.
- separate bundles for each big component/module inside drlvm/classlib.
This is how Alexei's scripts work now.
To me, structuring into subdirs is fine. It helps browsing, localizing
specific files, works marvelously for the wiki metrics pages...
BUT!
With subdirs, you never get a full list of files/funcs/structs/etc for
the whole drlvm and if you search for a specific item, you'll have to go
from bundle to bundle.
This can be partially fixed by an opening page with links to specific
component bundles. However, indexing and search would still be
component-wise only.
There might be more arguments pro and contra. Everyone - please express
your preference!
PS: Alexei, thanks for a warm welcome, I'll work hard to meet your
expectations.
Cheers,
Nadya
-----Original Message-----
From: Alexei Fedotov [mailto:[EMAIL PROTECTED]
Sent: Friday, November 24, 2006 4:33 AM
To: [email protected]
Subject: Re: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
Nadya,
My congratulations with your new role. Now I believe nothing will
prevent Harmony web site and documentation from being the best and the
coolest one. :-)
I have prepared a documentation update according Andrey's Wiki page
(with Egor's and Pavel's comments), see the last comment to
http://issues.apache.org/jira/browse/HARMONY-2024. The documentation
contains component bundles and inter-component interface bundle. If
you find results useful, please don't hesitate to ask questions about
how it works.
I also updated documentation metrics per bundle at the Wiki page:
http://wiki.apache.org/harmony/DRLVM_Documentation_Quality
Many of .html files contain "The documentation for this struct was
generated from the following file:" footer, so it shouldn't be a
problem to understand which source file should be editied to improve
the metrics.
--
Thank you,
Alexei
On 11/21/06, Morozova, Nadezhda <[EMAIL PROTECTED]> wrote:
-----Original Message-----
From: news [mailto:[EMAIL PROTECTED] On Behalf Of Egor Pasko
Sent: Tuesday, November 21, 2006 7:42 AM
To: [email protected]
Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
On the 0x227 day of Apache Harmony Nadezhda Morozova wrote:
That's a great start. Yes, if we have such a table as the front
page
for
Doxygen interfaces, it would be great. If you wish, I can prepare
the
patch with the nice-looking version of it all.
Questions:
- When building Doxygen, can we have a target for inter-component
interfaces and for each component?
- if yes, should the files inside the include/ subfolder be built
with
the component they belong to?
- For VM core and jit: any ideas on how to group files further?
The
current list of files belonging to vm core interfaces is *so*
long...
- Should we prepare docs for gcv4?
IMO, the list of headers for Jitrino is too verbose. For
inter-component picture I suggest the following subset:
vm/jitrino/src/dynopt/EdgeProfiler.h
vm/jitrino/src/dynopt/StaticProfiler.h
vm/jitrino/src/jet/jet.h
vm/jitrino/src/main/Jitrino.h
vm/jitrino/src/vm/drl/DrlEMInterface.h
vm/jitrino/src/vm/drl/DrlVMInterface.h
vm/jitrino/src/vm/EMInterface.h
vm/jitrino/src/vm/VMInterface.h
other headers are internal for Jitrino. So, the suggestion is: to
document the mapping between *relevant* h-files and the structure in
the DevGuide
[Nadya]
I think we're mixing two different header groups. The first type is
*inter-component*, listed at the top of page on wiki. The devguide
shows
these interfaces in VM arch figure. As I understand, these are the
interfaces that any jit must export:
Execution engine
JIT_VM
vm/include/internal_jit_intf.h
vm/include/open/ee_em_intf.h
Not sure how these are related to files jitrino/src/vm/*Interface.h.
The other group is *Interfaces inside the components*. Here I think
all
interfaces between internal parts of a component can go. I agree JIT
and
VM core seem to have too many headers, but they are all in the dir
tree.
Don't you think we need to document them?
My suggestion would be to add subgrouping for jit header files - and
possibly assign priorities to different groups. What do you say?
Thank you,
Nadya Morozova
-----Original Message-----
From: Andrey Yakushev [mailto:[EMAIL PROTECTED]
Sent: Monday, November 20, 2006 3:47 PM
To: [email protected]
Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
In order to understand the mapping between h-files and structure
described in the Developers guide I have tried to prepare some
initial
classification. I put draft at
http://wiki.apache.org/harmony/DRLVM_Documentation_Interfaces_Classific
atio
n.
Probably such tables could be added to Doxygen doc; of course
after
verification and rewriting it in more user friendly manner.
Is this helpful?
Thanks,
Andrey
On 11/7/06, Mikhail Fursov <[EMAIL PROTECTED]> wrote:
On 07 Nov 2006 21:17:45 +0600, Egor Pasko
<[EMAIL PROTECTED]>
wrote:
Do we feel that it is time to set responsibilities on
documenting
vm/include/* ?
+1 To start working on intercomponent interfaces. Going to
commit
a
couple
of EM interface files with documentation tomorrow. I do not
believe
that
someday we will have all component's local code documented (-1
to
make
such
policy for patches), but intercomponent documentation is
something
we
must
have (actually we must not only document but clean the code
too)
--
Mikhail Fursov
--
Egor Pasko
