Bugzilla – Full Text Bug Listing
| Summary: | [releng] OCL Help TOC doesn't appear. | ||
|---|---|---|---|
| Product: | [Modeling] OCL | Reporter: | Adolfo Sanchez-Barbudo Herrera <adolfosbh> |
| Component: | Core | Assignee: | Adolfo Sanchez-Barbudo Herrera <adolfosbh> |
| Status: | CLOSED FIXED | QA Contact: | |
| Severity: | normal | ||
| Priority: | P1 | CC: | eclipse, ed |
| Version: | 3.1.0 | ||
| Target Milestone: | M6 | ||
| Hardware: | PC | ||
| OS: | Windows 7 | ||
| Whiteboard: | |||
|
Description
Adolfo Sanchez-Barbudo Herrera
As a first insight, I think that the problem is that the javadoc is not generated by the buckminster build... Looking into this. Regards, Adolfo. Well, Our build/publishing process has been configured to: 1. Generate javadoc during the build process which will be included as part of the result artifacts of the build. 2. Publish the javadoc from the last successful build, in the correspondent javadoc area. Currently: http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/index.html I also have a patch ready for commit to fix the OCL API Reference. However, there is also another problem. There are some documentation concerning the extension points which are expected by the Help, which is not present in the doc plugin, and I suspect that it was generated by the same process which generated the javadoc. I think that all these questions concerning this pde-generated documentation + buckminster should be moved up to the PMC. By the way, I would like to solve this bug without expending more time about what to do with the extension-point documentation. Moreover, there are a lot of projects (whose builds are based on buckminster) which are not including any API Reference (javadoc and extension points) in their documentation plugins.... So I think we could: 1. Solve this bug in the current state (without any extension point doc). 2. Move the question/problem to the PMC 3. Fix (if apply) any pendant documentation issue (depending on what PMC says). Comments ? Cheers, Adolfo. (In reply to comment #2) > Comments ? Once you assign a bug to yourself, you stop traffic going to mdt-ocl inbox, that all committers should watch, so unless a committer added as CC on first notification you won't have anyone listening. I only picked this up becuase of your email reference. I suggest not assigning. > So I think we could: > > 1. Solve this bug in the current state (without any extension point doc). > 2. Move the question/problem to the PMC > 3. Fix (if apply) any pendant documentation issue (depending on what PMC says). I thought we'd agreed to have Javadoc as a reference to the www area, so that there is very little mandatory build activity. (In reply to comment #3) > (In reply to comment #2) > > Comments ? > > Once you assign a bug to yourself, you stop traffic going to mdt-ocl inbox, that > all committers should watch, so unless a committer added as CC on first > notification you won't have anyone listening. > > I only picked this up becuase of your email reference. I know, that reference in the email was intentional ;P > > I suggest not assigning. > I don't agree: - Assigning is a good way to assign responsibility. - It also helps me to track the bugs I'm responsible in mylin. - Other committers dont receive extra emails if they are not responsible of the bug and/or are nor interested in. If they are, they should add themself to cc when creating the bug or when the bugs changes to the assigned status It's my task when requiring extra information to ensure that interested people are in CC. In this case instead of adding you to cc I simply sent an email to dev list to send extra information. > > So I think we could: > > > > 1. Solve this bug in the current state (without any extension point doc). > > 2. Move the question/problem to the PMC > > 3. Fix (if apply) any pendant documentation issue (depending on what PMC > says). > > I thought we'd agreed to have Javadoc as a reference to the www area, so that > there is very little mandatory build activity. When I said "current state" I meant including the progress I've made (including the javadoc). So what I'm really suggesting is solving the bug by: - Having javadoc a a reference to the www area. - Removing the content from the TOC which concerns extension-point documentation, specifically "org.eclipse.ocl.environments" which will be deprecated in Indigo anyway, am I wrong ? Cheers, Adolfo. (In reply to comment #4) > - Removing the content from the TOC which concerns extension-point > documentation, specifically "org.eclipse.ocl.environments" which will be > deprecated in Indigo anyway, am I wrong ? We shouldn't remove functionality just because we don't understand it. Part of the early post-Indigo API 'alignment' will be attempting to ensure that we have a new functionality for all old functionality. Till I understand the EP, I cannot comment on its replacement. Ed I'm not saying to remove the extension-point... I only want to remove from our o.e.ocl.doc plugin, the Help's topic which contains the description/documentation about said extension point (which was inserted in our doc plugin by the old build system)... The extension point and its description/documentation will obviously be in the org.eclipse.ocl plugin - Again, we need to hear from the PMC about what should and what should not be included in our project Documentation plugin. - If we must include EP documentation in our .doc plugin, I hope buckminster provide any kind of mechanism to do what the old build system does. - If it provides said mechanisms, every project (including EMF, OCL, Xtext, Acceleo,...) will have to adopt this solution. Cheers, Adolfo. (In reply to comment #2) > 1. Solve this bug in the current state (without any extension point doc). > 2. Move the question/problem to the PMC > 3. Fix (if apply) any pendant documentation issue (depending on what PMC says). How about consulting the PMC for advice regarding the extension point docs? Also, do we know of other projects where these docs are generated properly? Any possibility we may get their advice, too? Best, -- Axel Sure, I've just sent an email to modeling-pmc newsgroup: http://dev.eclipse.org/mhonarc/lists/modeling-pmc/msg01964.html Regards, Adolfo. - Created a references/javadoc/index.html which simply redirects to http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/index.html - Extension-Point topic removed (waiting for any guidance by PMC concerning this). Changes committed to HEAD. Although this works in my second instance, I'll verify the fix (and resolve the bug) using the Modeling Indigo M6 installation. Cheers, Adolfo. Now that M6 modeling distribution is available, I could verify that OCL Help doesn't work... I guess that I'll definitely need to deal with that build.xml, providing that now we don't want to include javadoc in the doc plugin. Looking into this... The problem was that the previous system build was not relying on the build.properties file to produce the doc bundle/jar. Buckminster relies on this file to generate the jar, and some files (including TOC files) needed to be specified in the build.properties file so that they were included into said jar. Besides, now that I know how to interfere a component build done by buckminster, I've also successfully tried to invoke an ant task which creates the extension point documentation into the doc plugin. The javadoc creation counterpart has been commented because as discussed weeks ago, we don't want to include javadoc into the documentation plugin. To test the documentation you could update the OCL Extender feature (which includes the documentation) using our P2 nightly repository [1]. [1] http://wiki.eclipse.org/MDT/OCL/Dev/Releng/P2_Repositories_Organization#Nightly_Repository Axel detected that help's links which refer to the javadoc are not working. The problem is the link URLS are relative to a references/javadoc folder which is not currently built inside the plugin. We must use absolute URLs pointing to our javadoc area (http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/) I've checked some links in the Help and they are now working using the last published build. I must note that there are two external javadoc references, which may be considered to be updated in future releases http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/ http://download.eclipse.org/modeling/emf/emf/javadoc/2.6.0/ Resolving as fixed. Closing |