harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Alexei Fedotov" <alexei.fedo...@gmail.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Fri, 24 Nov 2006 16:18:34 GMT
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