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: Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Tue, 28 Nov 2006 14:31:19 GMT
>BTW, do we have vm.cfg committed as well as all other stuff necessary
>to generate Doxygen docs?

Yes, see JIRA 2024 and download the doc.scripts.zip bundle. It has the
build file, the vm.cfg for Doxygen and the doc.properties to feed as the
build targets. 
Unload the files into the vm/doc/ directory and run ant. Should work.

Cheers, 
Nadya
 

>-----Original Message-----
>From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>Sent: Tuesday, November 28, 2006 2:20 PM
>To: dev@harmony.apache.org
>Subject: Re: [doc] What should be improved in DRLVM Doxygen
documentation?
>
>On the 0x22E day of Apache Harmony Nadezhda Morozova wrote:
>> Thanks for valuable feedback! We've got so many things to do.
>
>u r welcome :)
>
>> I've used the key JIRA for Doxygen docs that we have now:
>> http://issues.apache.org/jira/browse/HARMONY-2024 submitted by Alexei
F.
>
>yes, I am looking in it too
>
>> There, we actually have two different doc sets:
>> Drlvm_intf_doc is for the whole bundle, and vm_doc.scripts.zip
enables
>> you to build component-wise documentation. Which one do we want?
>
>I prefer *full docs* for all source files so I could travel through
>the docs where I want. So, drlvm_intf_doc..
>
>> I've been thinking of how to best add Doxygen docs to the website,
>> suggest the following:
>>
>> standard/site/xdocs/subcomponents/classlib/doxygen/index.html - for
>> classlib bundle(s).
>> standard/site/xdocs/subcomponents/drlvm/doxygen/index.html - for
drlvm
>> bundle(s).
>> standard/site/xdocs/stylesheets/* - for the config files and scripts
to
>> build Doxygen documentation.
>> Any objections?
>
>Nadya, you have more expertise in this field :)
>
>BTW, do we have vm.cfg committed as well as all other stuff necessary
>to generate Doxygen docs?
>
>> Cheers,
>> Nadya
>>
>>
>> >-----Original Message-----
>> >From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
>> >Sent: Monday, November 27, 2006 1:04 PM
>> >To: dev@harmony.apache.org
>> >Subject: Re: [doc] What should be improved in DRLVM Doxygen
>> documentation?
>> >
>> >On the 0x22B day of Apache Harmony Alexei Fedotov wrote:
>> >> Ooops.... Sorry for incorrect word usage. I was intended to ask
who
>> >> will read Doxygen on our site and for which purpose. This would
help
>> >> us to understand what we should put there.
>> >
>> >From other projects I found Class hierarchy most useful in Doxygen.
It
>> >is also useful for beginners to see the top-level structure of the
>> >code in a comprehensive manner. See [1] as a live example of on-site
>> >doxygen in an opensource project.
>> >
>> >I love to travel through the code in vim+ctags, but it is not the
best
>> >for all. So, I would vote for putting the Doxygen docs on the site
as
>> >it should be useful. The sooner the better because it should help
>> >people express their opinions on _what should be improved_. Today it
>> >is not easy to say $subj if you do not see the docs out there.. have
>> >to download 10MB, etc. etc.
>> >
>> >I should have said that long ago.. but.. too busy, sorry :(
>> >
>> >Today I downloaded th 10MB drlvm_intf_doc.zip and looking at it.
>> >Some comments:
>> >* header page is too brief
>> >* no class hierarchy & class inheritance sexy pictures
>> >* no source code browsing
>> >* per-file view wastes a lot of space
>> >
>> >Let's have the next step forward: put doxygen docs on the site! And
>> >regenerate them regularly (=as snapshots appear, for
>> >example). How-to-improve opinions will come.
>> >
>> >[1]
http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html
>> >
>> >> On 11/24/06, Alexei Fedotov <alexei.fedotov@gmail.com> wrote:
>> >> > All,
>> >> >
>> >> > Let me support Nadya's request. The first thing we need to do is
to
>> >> > define what we are trying to achieve. Who is our target
auditory?
>> >> >
>> >> > 1. Egor said that he liked browsing object dependencies using
>> Doxygen.
>> >> > 2. Salikh said that he personally found browsing source files
much
>> more
>> >useful.
>> >> > 3. All my cases are about situations when one programmer used
>> >> > interfaces developed by another programmer.
>> >> >
>> >> > Could you please share your experience with wonderful
>> Doxygen/javadooc
>> >browsing?
>> >> >
>> >> >
>> >> > --
>> >> > Thank you,
>> >> > Alexei
>> >> >
>> >> > On 11/24/06, Morozova, Nadezhda <nadezhda.morozova@intel.com>
>> wrote:
>> >> > > 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:alexei.fedotov@gmail.com]
>> >> > > >Sent: Friday, November 24, 2006 4:33 AM
>> >> > > >To: dev@harmony.apache.org
>> >> > > >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 <nadezhda.morozova@intel.com>
>> wrote:
>> >> > > >>
>> >> > > >> >-----Original Message-----
>> >> > > >> >From: news [mailto:news@sea.gmane.org] On Behalf
Of Egor
>> Pasko
>> >> > > >> >Sent: Tuesday, November 21, 2006 7:42 AM
>> >> > > >> >To: dev@harmony.apache.org
>> >> > > >> >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:andrey.yakushev@gmail.com]
>> >> > > >> >> >Sent: Monday, November 20, 2006 3:47 PM
>> >> > > >> >> >To: harmony-dev@incubator.apache.org
>> >> > > >> >> >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_Classifi
>> c
>> >> > > >> >> 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 <mike.fursov@gmail.com>
wrote:
>> >> > > >> >> >> On 07 Nov 2006 21:17:45 +0600, Egor
Pasko
>> >> > > <egor.pasko@gmail.com>
>> >> > > >> >> 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
>> >> > > >>
>> >> > >
>> >> >
>> >>
>> >>
>> >> --
>> >> Thank you,
>> >> Alexei
>> >>
>> >
>> >--
>> >Egor Pasko
>>
>
>--
>Egor Pasko

Mime
View raw message