Hi All,
Thanks everybody for your replies. I have some doubts about how to
proceed, though.
So in order to clarify and ease things, I've ellaborated the
following simple questionaire to be discussed by the PMC in the next
meeting (or via this mailing list if desired):
1. How should a modeling project manage javadoc documentation:
a) Including it into project documentation plugin.
b) Making it available somewhere in downloads area.
c) Any of a) and b).
d) Both a) and b) options.
e) Javadoc is not required.
2. How should a modeling project manage extension point
documentation:
a) Including it into project documentation plugin.
b) Making it public somewhere in downloads area.
c) Any of a) and b) options (at least one of them).
d) Both a) and b) options.
e) Extension point documentation is not required.
I suppose, that it could be also desirable to have a unique way to
deal with the process of creating/building the documentation
(preferably in an automatic way), also providing we are using
buckminster to do our builds. Anyway, I think that is mandatory,
nevertheless, it should be important to know which
content/documentation we must provide, where we must place it, etc
Best Regards,
Adolfo.
El 25/02/2011 14:01, Kenn Hussey escribió:
We made a decision to remove the generated Javadoc
from the EMF Help because it bloated downloads/updates
unnecessarily. We generate and publish updated Javadoc on the Web
for each release and, with the SDK installed, the Javadoc for a
given class is always available in the Javadoc View...
Kenn
On Fri, Feb 25, 2011 at 7:31 AM, Wenz,
Michael <michael.wenz@xxxxxxx>
wrote:
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
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/
_______________________________________________
modeling-pmc mailing list
modeling-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/modeling-pmc
_______________________________________________
modeling-pmc mailing list
modeling-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/modeling-pmc
|
