| [modeling-pmc] Javadoc for Eclipse Modeling Projects |
|
Hello PMC, After recently detecting a bug[1] concerning the MDT/OCL Documentation, we discovered that our transition to the buckminster-based build system missed the javadoc creation process. We have had interesting discussions concerning this issue in the bugzilla itself and in the mdt-ocl.dev newsgroup [2] & [3]. As a resume, we have taken the following decisions/actions: - Generate javadoc during the build process (in a similar way Xtext has done) and publish it in a project location in downloads [4]. - No include the javadoc into the org.eclipse.ocl.doc plugin (so that we don't increase our doc plugin size). - Update the MDT/OCL Help's TOC (Table of Content) so that the API Reference now points to the javadoc published in the project downloads [4]. However, we would like to get a consensus regarding this topic because: 1. We would like to ensure that we are doing well with these actions/decisions, and/or we are not missing any rule/policy concerning the documentation. 2. I think that every (modeling) project should do the same (not sure how other modeling projects are dealing with this), 3. As commented in the bugzilla, we still have a missed piece of the puzzle: Apart from the javadoc, the previous build system managed to create some documentation related to extension points inside the documentation plugin (org.eclipse.ocl.doc). We currently don't know what to do with this now: - Include/No include this extension points documentation in the doc plugin. - Publish/No publish this extension points documentation into downloads area. So I simply want to raise for the debate the following questions: - How are other modeling projects managing their buckminster-based builds to manage the javadoc and extension point documentation?, providing they are doing something. - Could the PMC clarify and/or discuss (via this newsgroup and/or next PMC meeting) what modeling project should do concerning said documentation ? An extra question/concern: - I've realized that in our download area there is javadoc for a lot of MDT/OCL releases[5]: 1.0.1, 1.1.0, 1.1.1, 1.1.2,... 3.1.0. Should I move javadoc from old releases to somewhere in archive ? Best Regards, Adolfo. [1] https://bugs.eclipse.org/bugs/show_bug.cgi?id=337202 [3] http://dev.eclipse.org/mhonarc/lists/mdt-ocl.dev/msg00749.html [3] http://dev.eclipse.org/mhonarc/lists/mdt-ocl.dev/msg00751.html [4] http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/ [5] http://download.eclipse.org/modeling/mdt/ocl/javadoc/ --
|
