Hi Folks,
In order to fix https://bugs.eclipse.org/bugs/show_bug.cgi?id=337202
by M6+1, on Monday, we will temporarily be adopting:
1.b) Making javadoc available in downloads area -> http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/
2.e) Extension point documentation is not required.
As soon as any decision around this topic is taken and/or I find
some time to look into it, I'll try to find a good way to better
deal with extension point documentation.
Two things more:
- I've tried to find here http://wiki.eclipse.org/Modeling_PMC_Meetings
any planned PMC meeting to include a point to discuss about this
topic. However, there is not any entry since 5 months ago. I'm not
sure if there has been any meeting, if minutes were not written, or
there is a different way to track these meetings.
- I've recently configured our buckminster-based build so that the
javadoc management (creation and promotion) is driven by a hudson
boolean parameter (default false), so that, when desired (scheduled
builds, thus, milestones and releases), we simply have to "check"
the parameter to make the build include the javadoc and to make the
promotion scripts publish said javadoc in our downloads area. On the
other hand, when doing nightly builds (MANAGE_JAVADOC = false) we
save job execution time and space in hudson by not
creating/publishing any javadoc. If any releng is interested, you
may find some information in the following bugzilla
(https://bugs.eclipse.org/bugs/show_bug.cgi?id=339076 ). You may
also use mdt-ocl.dev newsgroup and/or my email for extra
information.
Best Regards,
Adolfo.
El 28/02/2011 11:57, Adolfo Sánchez-Barbudo Herrera escribió:
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
|
