Nadya, Thanks for answers. You have a nice approach to the requirement engineering for the documentation build system. It would be great if you also add priorities for your requirements.
Looking into your original list of requirements, I've noticed I haven't addressed the second one: >2. Ability to see docs on the website Yesterday I'd added an archive with documentation to HARMONY-2024 http://issues.apache.org/jira/browse/HARMONY-2024, so committers could now put documentation to the web site and everyone could contribute to the documentation quality. With best regards, Alexei Fedotov, Intel Java & XML Engineering >-----Original Message----- >From: Morozova, Nadezhda [mailto:[EMAIL PROTECTED] >Sent: Tuesday, October 31, 2006 9:02 PM >To: harmony-dev@incubator.apache.org >Subject: RE: [doc] No Doxygen reference for code :( > >Alexei, > >Thanks for meaningful and numerous questions, Alexei. I have thought of >some of these, but you give it a systematic touch :) >Others' opinions are welcome, mine in below - marked with [NM]. > >Related question: do we want to have some version of API doc on the site >now? I've experimented with building docs, and could produce a working >bundle. We can work to enable the build create API docs locally in >parallel with that. > >PS: Geir, there's a specific question for you below. > >Thank you, >Nadya Morozova > > >-----Original Message----- >From: Fedotov, Alexei A [mailto:[EMAIL PROTECTED] >Sent: Tuesday, October 31, 2006 7:49 PM >To: harmony-dev@incubator.apache.org >Subject: RE: [doc] No Doxygen reference for code :( > >Nadya, All, > >Suggestion to generate Doxygen from DRLVM code sounds very interesting. >I posted a quick solution for Linux to >http://issues.apache.org/jira/browse/HARMONY-2024 > >[NM] great news, I'll see if I can do smth similar for Windows. > >If you want to have this integrated into build.xml, it would be great to >define a correct scope. Could you please give more details what do you >expect from the documentation build file? >[NM] I'd give it a try. Please don't expect me to write a design doc for >you > >A volunteer can try doing some things important for you first, and then >add new features gradually. >[NM] yeah, I like the idea of a gradual step-by-step process. > > * Should doxygen build documentation for inter-component interfaces? >[NM] sure, and I guess it's the better-documented part ;) > > * What are components? I assume vm, jit, gc are out of the question. Is >am execution manager or an interpreter a separate component? >[NM] see dev guide; we've thought components roughly match to top-level >folders: EM, Interpreter, TM are all components. Not sure what to do >with the three GCs now, though. > > * Should doxygen build documentation for each component like vm, jit, >interpreter, gc? >[NM] It's my dream and very convenient. Getting Doxygen to run for >half-hour and get hung doesn't seem an attractive prospect. However, I >guess we can get some primitive build as a start and add >component-specific build targets later. For me, an ideal list of targets >for Doxygen would be something like: ><all> - all headers for DRLVM/classlib (one of two, not both in one >bundle) ><inter-component> - headers in include/ folder basically. Do we have any >high-level interfaces in other places? This could show the "big picture" >and somehow map to the arch description. ><component> - headers for the component name specified. >We might concentrate on the first two now for simplicity and smaller >scope. > > * Should we put documentation into doc/<component>_doc dirs as class >library code does? >[NM] this is a complex issue. I know Geir has wanted to add website to >the snapshot. *Geir*, could you express your view on where to place >docs? I guess separating "normal" docs and "autogenerated" docs would be >good, like the /doc/ folder for all files, with /doc/Doxygen/ subfolder >for API reference. When we are ready to build component-specific >reference, /doc/Doxygen/ can have subfolders for each. > > * Should we use the same formatting as a class library documentation? >[NM] why not? as I've noticed, default formatting is ok, but there are >many options you can enable/disable, e.g. diagram for class hierarchy. > > * We don't need to process .cpp files in DRLVM source tree, do we? >[NM] no, I guess not. A developer that needs explanation in .cpp would >rather look into the code, I guess. > > * Would each of these choices (inter-component documentation, component >interface documentation) be a separate configuration? If yes, should we >put each result into the separate directory? > * Should doxygen process .java files in DRLVM source tree? > * Should the doxygen documentation be integrated with class library >documentation? >[NM] I hope we can have two different bundles. Otherwise, it'd take our >poor Doxygen a day to compile the docs :) we can cross-reference the two >index.html files. >Can you estimate, how often you'd want to link from a vm header >description into classlib? > > * Do you expect to have inheritance diagrams? >[NM] I don't know. From what I see, you don't have complex inheritance >that needs a diagram too often. A 2-3 level list would often be enough. >What do you say? >* Do we need to download Graphviz, or should we expect it preinstalled? >[NM] which is simpler? I guess a person that wants to build the doc >suspects that the parsing lib is needed. > > * A related question is how many platforms should we support. For >example, should I add downloading and compilation of Graphviz for my >SuSE Linux? >[NM] oh well, I don't know. Perhaps, we can have a README or some other >file that explains what to do to build docs successfully? > > * Should we have different documentation for Windows and Linux? >[NM] would resulting docs be different or the same? > > * If something is optional for now, what should be added in future? >[NM] I don't know - it's the future! > > * Is there any choice for user to affect resulting documentation? >[NM] I don't have a strong opinion about it, but Doxygen's main idea is >to get docs straight from code. So any change to doxygen's input should >probably be a patch in JIRA. We've had such patches before. > >With best regards, >Alexei Fedotov, >Intel Java & XML Engineering > >>-----Original Message----- >>From: Morozova, Nadezhda [mailto:[EMAIL PROTECTED] >>Sent: Tuesday, October 31, 2006 4:34 PM >>To: harmony-dev@incubator.apache.org >>Subject: [doc] No Doxygen reference for code :( >> >>Hi everyone, >> >>I've noticed that there's no API reference documentation for Harmony >>code - generated by Doxygen/Javadoc. I guess many will agree that >>having API reference is very useful and convenient. >> >> >> >>This issue was discussed a while ago [1] for kernel classes and vmi >>interface in classlib. We agreed to store the Doxygen docs on the >>website by generating them manually from code and placing there. It >>seems that the old version of the docs was removed from SVN but never >>made its way to the website, so it's just NOWHERE now :-(. Let's fix >it! >> >> >>AFAIU, we want to have the following: >> >>1. Ability to generate docs locally from source code as part of >>build - need to change existing build files or write new ones. >>2. Ability to see docs on the website - manually copy a local >>bundle of docs to the website and add a link. Geir has been planning to >>include the website into the next snapshot; supplying ready reference >>with it seem nice. >> >>Volunteers? >> >>I can work on item 2 for sure to get a nice config file and patch the >>website to link to our new Doxygen API. Item 1 -fixing the build - >might >>be more extravagant, so your aid's welcome ;) >> >> >> >>[1] mail thread >>http://mail-archives.apache.org/mod_mbox/incubator-harmony-dev/200609. m >b >>ox/[EMAIL PROTECTED] >> >> >> >>Thanks, >> >>Nadya Morozova
