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 Wed, 29 Nov 2006 07:38:50 GMT
On the 0x22F day of Apache Harmony Nadezhda Morozova wrote:
> >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.

So, the answer is "No" because it is not committed. Thanks, I know the
JIRA. Aren't we ready to commit these?

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

-- 
Egor Pasko


Mime
View raw message