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:[EMAIL PROTECTED] On Behalf Of Egor Pasko > >Sent: Wednesday, November 29, 2006 10:39 AM > >To: [email protected] > >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:[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 > -- Egor Pasko
