Adolfo,
we (the Graphiti project) have decided to make our JavaDoc available via our doc plugin inside the Eclipse Help (can be obtained as a part of the Graphiti SDK feature). In our opinion this is the place where users of the framework will look for such stuff. The JavaDoc is built as a part of our nightly (dev) build inside our Hudson build job (not sure if we do it the same way as XText).
Downside of course is the size of our doc plugin.
This is the way we do that today, still we are open for suggestions/recommendations or a common procedure how to deal with the topic. On the other hand I’m not really sure if we can get to (or even need to have) the “one way” how to deal with JavaDoc, that will work for all projects (e.g. there will be different requirements for tool projects and framework projects).
Michael
From: modeling-pmc-bounces@xxxxxxxxxxx [mailto:modeling-pmc-bounces@xxxxxxxxxxx] On Behalf Of Adolfo Sánchez-Barbudo Herrera
Sent: Donnerstag, 24. Februar 2011 18:41
To: PMC members mailing list
Subject: [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/
