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:[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 > -- Egor Pasko
