Differences between revisions 52 and 53
Revision 52 as of 2007-10-23 10:44:29
Size: 5382
Editor: nadinem
Comment: updating with tasks to EOY, replacing table with a simple list
Revision 53 as of 2009-09-20 21:55:04
Size: 5424
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
This page stores all info on the documentation updates to improve website, and establishes perspective for further activities. We will try to keep up-to-date a list of documents that are planned for updates or creation.[[BR]] This page stores all info on the documentation updates to improve website, and establishes perspective for further activities. We will try to keep up-to-date a list of documents that are planned for updates or creation.<<BR>>
Line 6: Line 6:
[http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.html Doxygen materials] provide reference information on public interfaces of DRLVM and its components. This API reference is created semi-automatically from the source code. We are using several metrics to evaluate and track improvement of the quality of the reference materials: [[http://harmony.apache.org/subcomponents/drlvm/doxygen/intf/html/index.html|Doxygen materials]] provide reference information on public interfaces of DRLVM and its components. This API reference is created semi-automatically from the source code. We are using several metrics to evaluate and track improvement of the quality of the reference materials:
Line 8: Line 8:
 1. ["DRLVM Documentation Quality"] describes some rating of DRLVM code comments evaluation quality.
 1. ["DRLVM Documentation Quality Doxygen Warning Rating"] describes additional rating that shows the amount of warnings during the Doxygen files generation.
 1. ["DRLVM Documentation Interfaces Classification"] provides classification that helps to understand the mapping between h-files and structure described in the [http://harmony.apache.org/subcomponents/drlvm/developers_guide.html Developers' Guide].
 1. [[DRLVM_Documentation_Quality]] describes some rating of DRLVM code comments evaluation quality.
 1. [[DRLVM_Documentation_Quality_Doxygen_Warning_Rating]] describes additional rating that shows the amount of warnings during the Doxygen files generation.
 1. [[DRLVM_Documentation_Interfaces_Classification]] provides classification that helps to understand the mapping between h-files and structure described in the [[http://harmony.apache.org/subcomponents/drlvm/developers_guide.html|Developers' Guide]].
Line 12: Line 12:
To produce adequate and uniform results, we recommend following [http://wiki.apache.org/harmony/Code_Commenting some simple markup rules] when documenting a header. To produce adequate and uniform results, we recommend following [[http://wiki.apache.org/harmony/Code_Commenting|some simple markup rules]] when documenting a header.
Line 16: Line 16:
 1. [http://issues.apache.org/jira/browse/HARMONY-3262 HARMONY-3262] Covers VM_Common interface header files
 1. [http://issues.apache.org/jira/browse/HARMONY-3263 HARMONY-3263] Covers VM_JIT and VM_EM interface header files
 1. [http://issues.apache.org/jira/browse/HARMONY-3264 HARMONY-3264] Covers VM_Interpreter interface header files
 1. [http://issues.apache.org/jira/browse/HARMONY-3273 HARMONY-3273] Covers VM_GC interface and VM_Thread interface header files
 1. [http://issues.apache.org/jira/browse/HARMONY-3274 HARMONY-3274] Covers JNI and JVMTI interface header files
 1. [http://issues.apache.org/jira/browse/HARMONY-3275 HARMONY-3275] Covers Execution manager external interface headers
 1. [http://issues.apache.org/jira/browse/HARMONY-3277 HARMONY-3277] Covers Thread manager external interface headers
 1. [http://issues.apache.org/jira/browse/HARMONY-3278 HARMONY-3278] Covers Garbage collector and Execution engine external interface headers
 1. [http://issues.apache.org/jira/browse/HARMONY-3284 HARMONY-3284] Covers OS portability layer external interface
 1. [[http://issues.apache.org/jira/browse/HARMONY-3262|HARMONY-3262]] Covers VM_Common interface header files
 1. [[http://issues.apache.org/jira/browse/HARMONY-3263|HARMONY-3263]] Covers VM_JIT and VM_EM interface header files
 1. [[http://issues.apache.org/jira/browse/HARMONY-3264|HARMONY-3264]] Covers VM_Interpreter interface header files
 1. [[http://issues.apache.org/jira/browse/HARMONY-3273|HARMONY-3273]] Covers VM_GC interface and VM_Thread interface header files
 1. [[http://issues.apache.org/jira/browse/HARMONY-3274|HARMONY-3274]] Covers JNI and JVMTI interface header files
 1. [[http://issues.apache.org/jira/browse/HARMONY-3275|HARMONY-3275]] Covers Execution manager external interface headers
 1. [[http://issues.apache.org/jira/browse/HARMONY-3277|HARMONY-3277]] Covers Thread manager external interface headers
 1. [[http://issues.apache.org/jira/browse/HARMONY-3278|HARMONY-3278]] Covers Garbage collector and Execution engine external interface headers
 1. [[http://issues.apache.org/jira/browse/HARMONY-3284|HARMONY-3284]] Covers OS portability layer external interface
Line 30: Line 30:
If you want to make an impact in development and improvement DRLVM Doxygen documentation, feel free to contribute to [https://issues.apache.org/jira/browse/HARMONY/component/12310090 JIRAs filed against doc component]. If you want to make an impact in development and improvement DRLVM Doxygen documentation, feel free to contribute to [[https://issues.apache.org/jira/browse/HARMONY/component/12310090|JIRAs filed against doc component]].
Line 35: Line 35:
   * ["Platforms to Run Harmony Development Kit on"]
   * [http://harmony.apache.org/roadmap.html Porting matrix]
   * [http://harmony.apache.org/subcomponents/drlvm/index.html Overall DRLVM documentation]
   * [http://harmony.apache.org/subcomponents/drlvm/developers_guide.html#Porting_Layer Porting layer definition]
   * [http://harmony.apache.org/subcomponents/drlvm/doxygen/apr_extension/html/index.html Doxygen reference for DRLVM]
   * [[Platforms_to_Run_Harmony_Development_Kit_on]]
   * [[http://harmony.apache.org/roadmap.html|Porting matrix]]
   * [[http://harmony.apache.org/subcomponents/drlvm/index.html|Overall DRLVM documentation]]
   * [[http://harmony.apache.org/subcomponents/drlvm/developers_guide.html#Porting_Layer|Porting layer definition]]
   * [[http://harmony.apache.org/subcomponents/drlvm/doxygen/apr_extension/html/index.html|Doxygen reference for DRLVM]]
Line 41: Line 41:
 1. Update [http://harmony.apache.org/subcomponents/drlvm/debugging_VM_and_JIT.html Debugging the DRL Virtual Machine and the JIT Compiler]
 1. Improve [http://harmony.apache.org/subcomponents/drlvm/cp-verifier.html Bytecode verifier] description to improve wording, structure and style
 1. Update [[http://harmony.apache.org/subcomponents/drlvm/debugging_VM_and_JIT.html|Debugging the DRL Virtual Machine and the JIT Compiler]]
 1. Improve [[http://harmony.apache.org/subcomponents/drlvm/cp-verifier.html|Bytecode verifier]] description to improve wording, structure and style
Line 44: Line 44:
 1. Update [http://harmony.apache.org/subcomponents/drlvm/TM.html Thread Manager] description after new threading features are implemented  1. Update [[http://harmony.apache.org/subcomponents/drlvm/TM.html|Thread Manager]] description after new threading features are implemented
Line 46: Line 46:
 1. ["Website Improvement"] - suggestions on website improvement and the trial site version[[BR]]
 1. ["Doxygen Docs Look&Feel Improvements"] - suggestions on how to improve the look and feel of generated Doxygen documentation
 1. [[Website_Improvement]] - suggestions on website improvement and the trial site version<<BR>>
 1. [[Doxygen_Docs_Look&Feel_Improvements]] - suggestions on how to improve the look and feel of generated Doxygen documentation
Line 51: Line 51:
Folks, here is the place for your creation :) [[BR]]
Feel free to leave your ideas/suggestions/comments on documentation, either negative or positive, right here.[[BR]]
Folks, here is the place for your creation :) <<BR>>
Feel free to leave your ideas/suggestions/comments on documentation, either negative or positive, right here.<<BR>>
Line 55: Line 55:
Thank you for [http://harmony.apache.org/quickhelp_contributors.html Getting Started For Contributors] document :)[[BR]]It really helps me to build Class Library and DRLVM[[BR]]
---[[BR]]
Thank you for [[http://harmony.apache.org/quickhelp_contributors.html|Getting Started For Contributors]] document :)<<BR>>It really helps me to build Class Library and DRLVM<<BR>>
---<<BR>>

This page stores all info on the documentation updates to improve website, and establishes perspective for further activities. We will try to keep up-to-date a list of documents that are planned for updates or creation.
Certain pages do require help of technical experts, so, please, do not ignore the information below.

Doxygen API Reference Documentation

Doxygen materials provide reference information on public interfaces of DRLVM and its components. This API reference is created semi-automatically from the source code. We are using several metrics to evaluate and track improvement of the quality of the reference materials:

  1. DRLVM_Documentation_Quality describes some rating of DRLVM code comments evaluation quality.

  2. DRLVM_Documentation_Quality_Doxygen_Warning_Rating describes additional rating that shows the amount of warnings during the Doxygen files generation.

  3. DRLVM_Documentation_Interfaces_Classification provides classification that helps to understand the mapping between h-files and structure described in the Developers' Guide.

To produce adequate and uniform results, we recommend following some simple markup rules when documenting a header.

Many headers using in Doxygen reference generation lack ample and well-formatted comments. To get easily readable, complete and useful info for DRLVM interface reference and Java class library reference, the following JIRAs were opened:

  1. HARMONY-3262 Covers VM_Common interface header files

  2. HARMONY-3263 Covers VM_JIT and VM_EM interface header files

  3. HARMONY-3264 Covers VM_Interpreter interface header files

  4. HARMONY-3273 Covers VM_GC interface and VM_Thread interface header files

  5. HARMONY-3274 Covers JNI and JVMTI interface header files

  6. HARMONY-3275 Covers Execution manager external interface headers

  7. HARMONY-3277 Covers Thread manager external interface headers

  8. HARMONY-3278 Covers Garbage collector and Execution engine external interface headers

  9. HARMONY-3284 Covers OS portability layer external interface

You are welcome to contribute to any of the JIRAs listed above or to create new ones that improve quality of markup.

Website Docs

If you want to make an impact in development and improvement DRLVM Doxygen documentation, feel free to contribute to JIRAs filed against doc component.

Besides the open bugs, we have several enhancements in mind and some ongoing work that cannot easily map to one finite JIRA. The current list of activities includes the following items:

  1. Create Porting Guide to document what needs to be done to port Apache Harmony to other OSs, such as FreeBSD, Solaris, QNX, etc. For that task, the following materials can be useful:

  2. Update Developer's Guide: sections 4.1 and 4.8 about Initialization and Shutdown are out of date

  3. Update Debugging the DRL Virtual Machine and the JIT Compiler

  4. Improve Bytecode verifier description to improve wording, structure and style

  5. Publish BTI (Build Test Infrastructure) launching and usage instructions
  6. Update Thread Manager description after new threading features are implemented

  7. Create localized pages of popular pages, such as in Russian and Chinese
  8. Website_Improvement - suggestions on website improvement and the trial site version

  9. Doxygen_Docs_Look&Feel_Improvements - suggestions on how to improve the look and feel of generated Doxygen documentation


FEEDBACK

Folks, here is the place for your creation :)
Feel free to leave your ideas/suggestions/comments on documentation, either negative or positive, right here.
Do not hesitate to ask questions. I’ll try to do my best to satisfy your tiptoe curiosity :)


Thank you for Getting Started For Contributors document :)
It really helps me to build Class Library and DRLVM
---
Irlyanov Dmitry

Documentation_TODO (last edited 2009-09-20 21:55:04 by localhost)