harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrey Yakushev" <andrey.yakus...@gmail.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Fri, 24 Nov 2006 16:46:12 GMT
I'd like common Doxygen documentation bundle for all Harmony or at
least for all classlib and all DRLVM code. It suites for #1 and #3 use
cases, and I hope, even source readers also will be happy with
improved comments.

Thanks,
Andrey


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
> > >>
> >
>

Mime
View raw message