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 09:34:48 GMT
On the 0x230 day of Apache Harmony Nadezhda Morozova wrote:
> >So, the answer is "No" because it is not committed. Thanks, I know the
> >JIRA. Aren't we ready to commit these?
> Well,
> Largely, yes, though the config file does not allow for class hierarchy,
> file lists and graphics. I hope Alexei can adjust the scripts to check
> for the graphviz dot tool required for class diagrams. 
> Anyway, the scripts will be in the svn soon; I was also planning to
> generate the whole bundle and deposit on my home - just as Paulex did
> yesterday. 

thank you all for doing this!
graphvizing is great!

> Cheers, 
> Nadya
>  
> >-----Original Message-----
> >From: news [mailto:news@sea.gmane.org] On Behalf Of Egor Pasko
> >Sent: Wednesday, November 29, 2006 10:39 AM
> >To: dev@harmony.apache.org
> >Subject: Re: [doc] What should be improved in DRLVM Doxygen
> documentation?
> >
> >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
> 

-- 
Egor Pasko


Mime
View raw message