Adolfo,
We (mostly I) have been remiss in scheduling meetings. It seems there
was always yet another trip that conflicted with the scheduled 3rd
Tuesday of the month at 11:00AM Eastern; the next one is during the
EclipseCon week, so those of us there could chat. When we have them, I
do keep minutes.
Cheers,
Ed
Adolfo Sánchez-Barbudo Herrera wrote:
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
_______________________________________________
modeling-pmc mailing list
modeling-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/modeling-pmc
|
