>I think that they can go on the site in some way, but I just still don't >think we should check them in there. > >If we are checking the stuff into SVN, we should probably do so local to >where generated (DRLVM docs in drlvm part of svn...) and just use svn >externals from the web site...
Ok, what about having a starting page on the website with links to pages as svn externals for specific items? Silly question: if we keep the docs in svn with the respective code, can we force a re-build of the docs when the code is built? I mean, if somebody goes and checks out source code, they also check out the docs. unless re-generated, docs can be out-of-sync with the code. Related: if stored in svn, docs can get stale unless regenerated once in a while. Is this ok? Cheers, Nadya >-----Original Message----- >From: Geir Magnusson Jr. [mailto:[EMAIL PROTECTED] >Sent: Thursday, November 30, 2006 9:54 AM >To: [email protected] >Subject: Re: [doc] What should be improved in DRLVM Doxygen documentation? > >I think that they can go on the site in some way, but I just still don't >think we should check them in there. > >If we are checking the stuff into SVN, we should probably do so local to >where generated (DRLVM docs in drlvm part of svn...) and just use svn >externals from the web site... > >geir > >Morozova, Nadezhda wrote: >>> So, do we want to actually commit the generated content into the >> website >>> tree? I am kinda resistant to do so for reasons I can't defend very >> well. >> >> Well, the whole docset for drlvm only is ~5MB, with *many* pages empty >> now. We can dream of times when all of them are in an ideal shape, but I >> don't think it's realistic at this stage. If not, why have them? >> >> Suggested compromise: >> Have only the top-level interfaces documentation for DRLVM + classlib on >> site with ability to generate all the rest locally. >> For classlib, that could be kernels and vmi, for drlvm that could be >> intercomponent - mostly located in the vm/include folder (see accurate >> listing at >> http://wiki.apache.org/harmony/DRLVM_Documentation_Interfaces_Classifica >> tion >> >> For a clearer view, I'd post the drlvm docs on my home. If we agree >> these can go on site, would be great. Having a starting page for >> interfaces code on the site would be marvelous too. >> >> Cheers, >> Nadya >> >> >>> -----Original Message----- >>> From: Geir Magnusson Jr. [mailto:[EMAIL PROTECTED] >>> Sent: Wednesday, November 29, 2006 8:16 PM >>> To: [email protected] >>> Subject: Re: [doc] What should be improved in DRLVM Doxygen >> documentation? >>> >>> Morozova, Nadezhda 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. >>> So, do we want to actually commit the generated content into the >> website >>> tree? I am kinda resistant to do so for reasons I can't defend very >> well. >>> Certainly the scripts should be there... >>> >>> geir >>> >>> >>>> 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
