Nadya, Sorry, I supposed to say the same thing. By requirement engineering I meant a discussion of requirements.
With best regards, Alexei Fedotov, Intel Java & XML Engineering >-----Original Message----- >From: Morozova, Nadezhda [mailto:[EMAIL PROTECTED] >Sent: Wednesday, November 01, 2006 5:09 PM >To: harmony-dev@incubator.apache.org >Subject: RE: [doc] No Doxygen reference for code :( > >Alexei, >One note: I'm *not* writing requirements for engineering on the doc >build system. I'm just sharing my thoughts on an issue that interests >me. Discussion is welcome. Please don't consider my ideas as "the way it >should be". > >Thank you, >Nadya Morozova > > >-----Original Message----- >From: Fedotov, Alexei A [mailto:[EMAIL PROTECTED] >Sent: Wednesday, November 01, 2006 4:52 PM >To: harmony-dev@incubator.apache.org >Subject: RE: [doc] No Doxygen reference for code :( > >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
