From zhouyx at linux.vnet.ibm.com Wed Dec 5 02:20:11 2012 From: zhouyx at linux.vnet.ibm.com (Sean Chou) Date: Wed, 5 Dec 2012 18:20:11 +0800 Subject: A JEP draft for documenting the Class Library/JVM interfaces Message-ID: Hi all, I'm working with Neil on the project of improving the documentation of Class Library/JVM interfaces [1]. We created a simple demo about what the documentation work would look like, as well we wrote a JEP draft based on the demo. We hope to get enough comments and put it into JEP process before next Friday(Dec 14). Here is the content of the draft(also in attachment): Title: Building documents for Class Library/JVM interfaces Author: Organization: IBM Owner: Created: 2012/12/01 Type: Informational State: Draft Exposure: Open Component: core/libs, vm/-- Discussion: cvmi dash dev at openjdk dot java dot net Start: 2013/Q1 Effort: S Duration: S Template: 1.0 Internal-refs: Reviewed-by: Endorsed-by: Funded-by: Summary ------- Enable the build infrastructure to build documents for Class Library/JVM interfaces Goals ----- 1. Enable the build infrastructure to generate documentation for Class Library/JVM interfaces. 2. Document the Class Library/JVM interfaces in a format supported by doxygen. Non-Goals --------- This JEP does not cover creating additional documentation. Success Metrics --------------- When docs of jdk is built, the document contains the Class Library/JVM interfaces. Motivation ---------- Besides JNI and JVMTI, the JVM still has a lot functions defined as library/JVM interfaces. Creating documentation for these functions can help class library develpers utilize the functions provided JVM. As well, it will help alternative JVM to use RI class library. Description ----------- This JEP is to add a build option to build the documents for Class Library/JVM interfaces. The exported JVM functions in jdk/src/share/javavm/export directories are used as the Class Library/JVM interfaces. The JEP includes following changes: 1. Doxygen will be added as a build dependency. 2. The build scripted will be modified to include the option of building the document. 3. The comment format in library/JVM interfaces needs to be updated to doxygen format. 4. A doxygen configuration file will be added. Here is an example what's the document and configuration file would look like. The built docs: http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/ An example of commented function: http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/jvm_8h.html#a05f1ec06295884dbb7519ddcf20f0e56 http://cr.openjdk.java.net/~zhouyx/cvmi/comment_modi/ The configuration file: http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/cvmi.conf The configuration file quite long, but most of it is created by template; the modification is samll. Following is the template and modification. http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/template.conf http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/config.diff Alternatives ------------ Write additional specification to document the interface like JNI and JVMTI specification. Dependences ----------- It is needed to add doxygen to build dependency, and the library/JVM interfaces needs to be documented in doxgen supported format. Impact ------ The Class Library/JVM interface will get its documents while building. ///////// End [1] http://mail.openjdk.java.net/pipermail/cvmi-dev/2012-May/000043.html -- Best Regards, Sean Chou -------------- next part -------------- Title: Building documents for Class Library/JVM interfaces Author: Organization: IBM Owner: Created: 2012/12/01 Type: Informational State: Draft Exposure: Open Component: core/libs, vm/-- Discussion: cvmi dash dev at openjdk dot java dot net Start: 2013/Q1 Effort: S Duration: S Template: 1.0 Internal-refs: Reviewed-by: Endorsed-by: Funded-by: Summary ------- Enable the build infrastructure to build documents for Class Library/JVM interfaces Goals ----- 1. Enable the build infrastructure to generate documentation for Class Library/JVM interfaces. 2. Document the Class Library/JVM interfaces in a format supported by doxygen. Non-Goals --------- This JEP does not cover creating additional documentation. Success Metrics --------------- When docs of jdk is built, the document contains the Class Library/JVM interfaces. Motivation ---------- Besides JNI and JVMTI, the JVM still has a lot functions defined as library/JVM interfaces. Creating documentation for these functions can help class library develpers utilize the functions provided JVM. As well, it will help alternative JVM to use RI class library. Description ----------- This JEP is to add a build option to build the documents for Class Library/JVM interfaces. The exported JVM functions in jdk/src/share/javavm/export directories are used as the Class Library/JVM interfaces. The JEP includes following changes: 1. Doxygen will be added as a build dependency. 2. The build scripted will be modified to include the option of building the document. 3. The comment format in library/JVM interfaces needs to be updated to doxygen format. 4. A doxygen configuration file will be added. Here is an example what's the document and configuration file would look like. The built docs: http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/ An example of commented function: http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/jvm_8h.html#a05f1ec06295884dbb7519ddcf20f0e56 http://cr.openjdk.java.net/~zhouyx/cvmi/comment_modi/ The configuration file: http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/cvmi.conf The configuration file quite long, but most of it is created by template; the modification is samll. Following is the template and modification. http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/template.conf http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/config.diff Alternatives ------------ Write additional specification to document the interface like JNI and JVMTI specification. Dependences ----------- It is needed to add doxygen to build dependency, and the library/JVM interfaces needs to be documented in doxgen supported format. Impact ------ The Class Library/JVM interface will get its documents while building. From spoole at linux.vnet.ibm.com Thu Dec 6 06:40:01 2012 From: spoole at linux.vnet.ibm.com (Steve Poole) Date: Thu, 6 Dec 2012 14:40:01 +0000 Subject: A JEP draft for documenting the Class Library/JVM interfaces In-Reply-To: References: Message-ID: <1755EC33-4531-4502-A94E-ED2E94A6C136@linux.vnet.ibm.com> hi Sean , thanks for posting this. I've copied in Mikael Vidstedt as I think he'll be interested (and probably not watching cvmi :-) ) On 5 Dec 2012, at 10:20, Sean Chou wrote: > Hi all, > > I'm working with Neil on the project of improving the documentation of > Class Library/JVM interfaces [1]. We created a simple demo about what > the documentation work would look like, as well we wrote a JEP draft > based on the demo. > > We hope to get enough comments and put it into JEP process before > next Friday(Dec 14). > > Here is the content of the draft(also in attachment): > > > Title: Building documents for Class Library/JVM interfaces > Author: > Organization: IBM > Owner: > Created: 2012/12/01 > Type: Informational > State: Draft > Exposure: Open > Component: core/libs, vm/-- > Discussion: cvmi dash dev at openjdk dot java dot net > Start: 2013/Q1 > Effort: S > Duration: S > Template: 1.0 > Internal-refs: > Reviewed-by: > Endorsed-by: > Funded-by: > > > Summary > ------- > > Enable the build infrastructure to build documents for Class Library/JVM > interfaces > > > Goals > ----- > > 1. Enable the build infrastructure to generate documentation for Class > Library/JVM > interfaces. > 2. Document the Class Library/JVM interfaces in a format supported by > doxygen. > > > Non-Goals > --------- > > This JEP does not cover creating additional documentation. > > > Success Metrics > --------------- > > When docs of jdk is built, the document contains the Class Library/JVM > interfaces. > > > Motivation > ---------- > > Besides JNI and JVMTI, the JVM still has a lot functions defined as > library/JVM > interfaces. Creating documentation for these functions can help class > library > develpers utilize the functions provided JVM. As well, it will help > alternative JVM to use RI class library. > > > Description > ----------- > > This JEP is to add a build option to build the documents for Class > Library/JVM > interfaces. The exported JVM functions in jdk/src/share/javavm/export > directories are used as the Class Library/JVM interfaces. > > The JEP includes following changes: > 1. Doxygen will be added as a build dependency. > 2. The build scripted will be modified to include the option of building > the document. > 3. The comment format in library/JVM interfaces needs to be updated to > doxygen format. > 4. A doxygen configuration file will be added. > > Here is an example what's the document and configuration file would look > like. > The built docs: > http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/ > An example of commented function: > > http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/jvm_8h.html#a05f1ec06295884dbb7519ddcf20f0e56 > http://cr.openjdk.java.net/~zhouyx/cvmi/comment_modi/ > The configuration file: > http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/cvmi.conf > > The configuration file quite long, but most of it is created by template; > the modification is samll. Following is the template and modification. > http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/template.conf > http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/config.diff > > > Alternatives > ------------ > > Write additional specification to document the interface like JNI and > JVMTI specification. > > > Dependences > ----------- > > It is needed to add doxygen to build dependency, and the library/JVM > interfaces needs to be documented in doxgen supported format. > > > Impact > ------ > > The Class Library/JVM interface will get its documents while building. > > > > > ///////// End > > [1] http://mail.openjdk.java.net/pipermail/cvmi-dev/2012-May/000043.html > > -- > Best Regards, > Sean Chou > From neil.richards at ngmr.net Tue Dec 18 02:50:05 2012 From: neil.richards at ngmr.net (Neil Richards) Date: Tue, 18 Dec 2012 10:50:05 +0000 Subject: A JEP draft for documenting the Class Library/JVM interfaces In-Reply-To: References: Message-ID: <1355827806.6578.9.camel@chalkhill> I am cross-posting this to the hotspot-dev mailing list, as people there may be interested in this proposed JEP. Note that the proposal is to document the VM interfaces upon which the class library relies in the /jdk repository (as opposed to documenting the interfaces the Hotspot VM provides in the /hotspot repository, in case there is any discrepancy between these two). Feedback on this (to the cvmi-dev list, please) would be most welcome. Regards, Neil On Wed, 2012-12-05 at 18:20 +0800, Sean Chou wrote: > Hi all, > > I'm working with Neil on the project of improving the documentation of > Class Library/JVM interfaces [1]. We created a simple demo about what > the documentation work would look like, as well we wrote a JEP draft > based on the demo. > > We hope to get enough comments and put it into JEP process before > next Friday(Dec 14). > > Here is the content of the draft(also in attachment): > > > Title: Building documents for Class Library/JVM interfaces > Author: > Organization: IBM > Owner: > Created: 2012/12/01 > Type: Informational > State: Draft > Exposure: Open > Component: core/libs, vm/-- > Discussion: cvmi dash dev at openjdk dot java dot net > Start: 2013/Q1 > Effort: S > Duration: S > Template: 1.0 > Internal-refs: > Reviewed-by: > Endorsed-by: > Funded-by: > > > Summary > ------- > > Enable the build infrastructure to build documents for Class Library/JVM > interfaces > > > Goals > ----- > > 1. Enable the build infrastructure to generate documentation for Class > Library/JVM > interfaces. > 2. Document the Class Library/JVM interfaces in a format supported by > doxygen. > > > Non-Goals > --------- > > This JEP does not cover creating additional documentation. > > > Success Metrics > --------------- > > When docs of jdk is built, the document contains the Class Library/JVM > interfaces. > > > Motivation > ---------- > > Besides JNI and JVMTI, the JVM still has a lot functions defined as > library/JVM > interfaces. Creating documentation for these functions can help class > library > develpers utilize the functions provided JVM. As well, it will help > alternative JVM to use RI class library. > > > Description > ----------- > > This JEP is to add a build option to build the documents for Class > Library/JVM > interfaces. The exported JVM functions in jdk/src/share/javavm/export > directories are used as the Class Library/JVM interfaces. > > The JEP includes following changes: > 1. Doxygen will be added as a build dependency. > 2. The build scripted will be modified to include the option of building > the document. > 3. The comment format in library/JVM interfaces needs to be updated to > doxygen format. > 4. A doxygen configuration file will be added. > > Here is an example what's the document and configuration file would look > like. > The built docs: > http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/ > An example of commented function: > > http://cr.openjdk.java.net/~zhouyx/cvmi/interface_doc/jvm_8h.html#a05f1ec06295884dbb7519ddcf20f0e56 > http://cr.openjdk.java.net/~zhouyx/cvmi/comment_modi/ > The configuration file: > http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/cvmi.conf > > The configuration file quite long, but most of it is created by template; > the modification is samll. Following is the template and modification. > http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/template.conf > http://cr.openjdk.java.net/~zhouyx/cvmi/config_file/config.diff > > > Alternatives > ------------ > > Write additional specification to document the interface like JNI and > JVMTI specification. > > > Dependences > ----------- > > It is needed to add doxygen to build dependency, and the library/JVM > interfaces needs to be documented in doxgen supported format. > > > Impact > ------ > > The Class Library/JVM interface will get its documents while building. > > > > > ///////// End > > [1] http://mail.openjdk.java.net/pipermail/cvmi-dev/2012-May/000043.html > -- Unless stated above: IBM email: neil_richards at uk.ibm.com IBM United Kingdom Limited - Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU