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
