Bugzilla – Full Text Bug Listing
| Summary: | [Refactoring] Define a standard plug-in documentation format | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Product: | [Modeling] Papyrus | Reporter: | Camille Letavernier <cletavernier> | ||||||||||||
| Component: | Core | Assignee: | Camille Letavernier <cletavernier> | ||||||||||||
| Status: | RESOLVED FIXED | QA Contact: | |||||||||||||
| Severity: | normal | ||||||||||||||
| Priority: | P3 | CC: | vincent.hemery, vincent.lorenzo | ||||||||||||
| Version: | unspecified | ||||||||||||||
| Target Milestone: | --- | ||||||||||||||
| Hardware: | PC | ||||||||||||||
| OS: | Windows XP | ||||||||||||||
| Whiteboard: | |||||||||||||||
| Bug Depends on: | |||||||||||||||
| Bug Blocks: | 359060 | ||||||||||||||
| Attachments: |
|
||||||||||||||
|
Description
Camille Letavernier
As far as I know, there is no mechanism in Eclipse to add documentation to a plug-in. There are a few properties in the Manifest (Provider, Name, and description), but the description doesn’t seem to be actually used by the platform anyway ; and we need more information (Especially regarding the “implicit dependencies”, which are not Java dependencies). Does anyone know about such a mechanism in Eclipse ? (E3, E4 ?) We’ve thought about the “package Javadoc” mechanism, but some plug-ins are not java-based (Model contribution, …) So, we have two solutions left : - A simple text (or *.properties) file - An EMF Model Unless a standard mechanism exists in Eclipse, the EMF Model seems to be the best approach. This only requires an EMF editor at development time (Although the generic EMF editor is not the best tool to edit the multiline comments…), and can be easily manipulated by tools. It is also easier to structure than a *.properties file, and we can add generic properties to the metamodel to allow some flexibility. Created attachment 204152 [details]
Sample Ecore metamodel
Sample Ecore metamodel for plug-in documentation
Created attachment 204153 [details]
Sample documentation model
Sample documentation model
Created attachment 204161 [details]
Ecore metamodel update proposal by vhemery
Hello, here are a few modifications I would make :
- Cardinalities 1..1 for Person and Comment current fields.
- Adding an optional (0..1) currentCompany field on Person.
I haven't modified it, but I am not sure about the cardinality we should have for the Documentation>referent field.
Current one is 0..*, but maybe it should be 1..*. If there is none, it clearly indicates a problem. Yet, it is not easy to assign one when we do not know who to assign. Maybe in such a case, we could assign a temporary fake Person ?
I've set a 0..* just for that problem, which is pretty common.
A model without a referent is "valid", but should have a warning (Not an error). Moreover, a plug-in may have more than one referent.
The fake person ("Unknown Referent", or alike) can be a solution. But there should be a way to obtain a *valid* model without knowing the actual reference (yet).
We may also investigate on the EMF Validation framework to add a warning on validation, when the referent is not set.
Regarding the person and comment, I agree with your modification.
For resource-based dependencies (Such as "I depend on this plug-in because it contains a model..."), we may add a specific kind of dependency ("FileDependency"), which can link to a File (or a Folder).
By doing this, it becomes easier to know whether the dependency is deprecated or not.
This could also be done form the generic dependency comment, but this would be harder to check with automated tools.
I don't have such an example yet, as all my model-based dependencies come along with Java-dependencies, thus don't need to be specified (Although this couldn't hurt to add them, to avoid surprises if we had to move the models to another plug-in).
Created attachment 204180 [details]
Ecore Metamodel v3
Created attachment 204181 [details]
Another Sample model
The model has been committed on the trunk/incoming with the following revisions : 5627-5633 : Initial imports 5638 : useability enhancements regarding the Model Editor org.eclipse.papyrus.documentation.plugin org.eclipse.papyrus.documentation.plugin.edit org.eclipse.papyrus.documentation.plugin.editor A basic model editor has been generated for manipulating the documentation model. It will most likely be replaced with a specific editor later on. The model can still be enhanced (or even totally replaced if we find a better solution matching our needs), but it is important that we can have a common basis to document our plug-ins before the refactoring. Tell me if there is a reason not to... But I would recommend to set the cardinality of FileDependency#file to 1..* instead of 1..1. This would allow to have a single FileDependency per plugin, even if there are many files needed in this plugin. For example, a plugin my.template provides a model template with files : - %name%.uml - %name%.notation - %name%.di (not sure the %name% is the way it is done, but doesn't really matter in this discussion) We define another plugin my.processtools which requires (functionnally) this template installed : This plugin provides process-specific tools (java validation, scripts...), which make sense only with a model based on this template. In such a case my.processtools depends on my.template. Its documentation has a FileDependency, but it makes sense only with the 3 files. Ok for 1..* I've set 1..1, because we can set a folder here, but UML Models are not always stored in a decidated folder. So, that's fine with me. |