>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. Cheers, Nadya >-----Original Message----- >From: news [mailto:[EMAIL PROTECTED] On Behalf Of Egor Pasko >Sent: Tuesday, November 28, 2006 2:20 PM >To: [email protected] >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:[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
