harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Geir Magnusson Jr." <g...@pobox.com>
Subject Re: [doc] What should be improved in DRLVM Doxygen documentation?
Date Wed, 29 Nov 2006 17:15:46 GMT

Morozova, Nadezhda 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. 

So, do we want to actually commit the generated content into the website 
tree?  I am kinda resistant to do so for reasons I can't defend very well.

Certainly the scripts should be there...

geir


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

Mime
View raw message