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 Mon, 27 Nov 2006 10:04:06 GMT
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_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 <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


Mime
View raw message