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