harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Egor Pasko <egor.pa...@gmail.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Tue, 28 Nov 2006 11:19:31 GMT
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