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:[EMAIL PROTECTED] On Behalf Of Egor Pasko > >Sent: Monday, November 27, 2006 1:04 PM > >To: [email protected] > >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 <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> > 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:[EMAIL PROTECTED] > >> > > >Sent: Friday, November 24, 2006 4:33 AM > >> > > >To: [email protected] > >> > > >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 <[EMAIL PROTECTED]> > wrote: > >> > > >> > >> > > >> >-----Original Message----- > >> > > >> >From: news [mailto:[EMAIL PROTECTED] On Behalf Of Egor > Pasko > >> > > >> >Sent: Tuesday, November 21, 2006 7:42 AM > >> > > >> >To: [email protected] > >> > > >> >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:[EMAIL PROTECTED] > >> > > >> >> >Sent: Monday, November 20, 2006 3:47 PM > >> > > >> >> >To: [email protected] > >> > > >> >> >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 <[EMAIL PROTECTED]> wrote: > >> > > >> >> >> On 07 Nov 2006 21:17:45 +0600, Egor Pasko > >> > > <[EMAIL PROTECTED]> > >> > > >> >> 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
