Bug 569357: [Toolsmiths] ElementTypes: Model and Plug-in Validation

Add documentation of plug-in builder usage and element-types validation rules.

Change-Id: I6bfff5d3e7a5998f8951d74deaccdc7ab62d82c4
Signed-off-by: Christian W. Damus <give.a.damus@gmail.com>

3 files changed, 69 insertions, 17 deletions

diff --git a/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/images/devDoc/Papyrus_ConfigurePluginNature.png b/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/images/devDoc/Papyrus_ConfigurePluginNature.png
new file mode 100644
index 00000000000..9765882d881
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/images/devDoc/Papyrus_ConfigurePluginNature.png
diff --git a/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/images/devDoc/Papyrus_PluginBuilderPreferences.png b/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/images/devDoc/Papyrus_PluginBuilderPreferences.png
new file mode 100644
index 00000000000..8bdf6b4dba9
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/images/devDoc/Papyrus_PluginBuilderPreferences.png
diff --git a/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/validationToolsmithsDevDoc.mediawiki b/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/validationToolsmithsDevDoc.mediawiki
index 15e35cf35b3..b38f195333b 100644
--- a/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/validationToolsmithsDevDoc.mediawiki
+++ b/plugins/doc/org.eclipse.papyrus.toolsmiths.validation.doc/src/site/mediawiki/validationToolsmithsDevDoc.mediawiki
@@ -1,10 +1,27 @@
-=General presentation=
-Some validations are available to validate the customizations of Papyrus:
-* Validation of a created '''profile''' into a plug-in
-* Validation of '''element types''' plug-in
-* Validation of '''architecture''' plug-in
+=Overview=
+Papyrus provides for validation of tooling models for DSML and other customization plug-ins, including:
+
+* Validation of a UML '''profiles''', both static (generated) and dynamic
+* Validation of '''element types configurations'''
+* Validation of '''architecture domain''' models
+
+Validation is provided on-demand via the '''Papyrus Developer''' context menu and optionally also as a project builder.
+
+==Papyrus Plug-in Builder==
+
+To enable automatic validation of tooling models in your customization plug-ins, configure the '''Papyrus Plug-in''' nature on
+your customization plug-in projects. In the context menu for your project, select the '''Configure → COnvert to Papyrus Plugin''' action:
+
+[[File:images/devDoc/Papyrus_ConfigurePluginNature.png|frame|none|Configure the Papyrus Plug-in project nature]]
+
+What is checked by the builder depends on settings in the '''Preferences'''. By default, the '''Papyrus Plug-in Builder''' performs no validation.
+To configure it, open the '''
+
+==Profile Plug-in Validation==
+
+All checks described in this section apply equally to on-demand validation via the context menu and
+automatic validation by the '''Papyrus Plug-in Builder'''.
 
-==Profile plug-in validation==
 ===What is checked?===
 To validate a profile plug-in, we have some points to check. Here are the checked points:
 * For each profile found in the plug-in:
@@ -21,6 +38,18 @@ To do this, select the project, then ''''Papyrus Developer''''>''''Validate Prof
 
 When you do a validation, the result of old profile plug-in validation are clean and the current problems are displayed in the corresponding view.
 
+[[File:images/devDoc/Papyrus_PluginBuilderPreferences.png|frame|none|Papyrus plug-in builder preferences]]
+
+There are a number of options available to enable:
+
+* whether to check anything at all when building a Papyrus project
+* whether to validate Papyrus tooling customization models. And, if so, whether to
+** check that model dependencies implied by tooling models are included in the bundle manifest
+** check other well-formedness rules of the models, themselves
+* whether to validate bundle and plug-in manifests. And, if so, whether to
+** check for the anti-pattern of dependency re-exports
+** check for the recommended practice of constraining bundle dependencies with compatible version ranges
+
 ===Where find the result?===
 The result is display in the ''''Problems'''' view and are categorized by the type ''''Papyrus Toolsmiths Profile Plug-in problems''''.
 
@@ -28,20 +57,43 @@ The result is display in the ''''Problems'''' view and are categorized by the ty
 
 Like others problems, you can double-click on one to open the concerning file. You can delete problem too when you think it is managed.
 
-==Element types plug-in validation==
+==Element Types Plug-in Validation==
 ===What is checked?===
 To validate a element types plug-in, we have some points to check. Here are the checked points:
-* Validation of the needed dependencies: '''WARNING'''
+* Bundle manifest dependencies on core element-types framework bundles: '''WARNING'''
 ** 'org.eclipse.papyrus.infra.types.core'
-** 'org.eclipse.gmf.runtime.emf.type.core'
-** 'org.eclipse.papyrus.uml.service.types'
-** 'org.eclipse.papyrus.infra.services.edit'
 ** 'org.eclipse.papyrus.infra.types'
-** 'org.eclipse.papyrus.uml.tools.utils'
-* For each element types files found in the plug-in:
-** Validation of the element types file itself: '''ERROR'''
-** Validation of the element types definition into the 'plugin.xml' file: '''ERROR'''
-** Validation of the dependencies needed in the 'MANIFEST.MF' file for the external dependencies of the element types file: '''WARNING''' (because maybe the dependency is not really needed (implicit dependence?))
+* For each element types copnfiguration model found in the plug-in:
+** Validation of the element types file itself: errors or warnings as described for different elements, below
+** Validation of the element types model registration in the 'plugin.xml' file
+*** if there is a registration on the extension point, and it omits the client-context ID: '''ERROR'''
+*** if there is no registration extension and there is no architecture model that references it: '''WARNING'''
+** Validation of bundle dependencies in the 'MANIFEST.MF' file implied by the element-types configuration model:
+*** missing dependency on the bundle that deploys the metamodel referenced by NS URI: '''ERROR'''
+*** referenced metamodel NS URI that cannot be resolved to a bundle that provides the metamodel: '''ERROR'''
+*** missing dependency on the bundle that deploys a referenced element-types model: '''ERROR'''
+*** missing dependency on the bundle that deploys a profile referenced by UML stereotype element-types: '''ERROR'''
+
+There are special element-types configuration elements available for definition of element types on the basis of the
+stereotypes in UML profiles. These are validated for availability or suitability of the referenced UML profile constructs:
+* ''Apply Stereotype Advice''
+** profile referenced by qualified name is not found in the workspace nor in the target platform: '''ERROR'''
+** stereotype referenced by qualified name is not found in any profile in the workspace nor in the target platform: '''ERROR'''
+** a ''Feature to Set'' is not contained by an ''Apply Stereotype Advice Configuration'': '''ERROR'''
+** a ''Feature to Set'' references a feature that the stereotype does not have: '''ERROR'''
+* ''Stereotype Application Matcher'' (and, by inheritance, the ''Stereotype Application Matcher Advice'')
+** profile referenced by namespace URI is not found in the workspace nor in the target platform: '''ERROR'''
+** stereotype referenced by qualified name is not found in any profile in the workspace nor in the target platform: '''ERROR'''
+* ''Stereotype Property Reference Edge Advice''
+** stereotype referenced by qualified name is not found in any profile in the workspace nor in the target platform: '''ERROR'''
+** the feature to set references a feature that the stereotype does not have: '''ERROR'''
+** the feature to set does not have a type, and therefore cannot be set: '''ERROR'''
+
+The rules above are not checked in the ''Element Types Configurations Editor'' while editing a model because they
+depend on the deployment of dependent resources in tooling bundles. Therefore, they are only checked by the
+tooling validation mechanisms described in this documentation. Other intrinsic model well-formedness constraints
+for element types configurations are checked by the editor; they are described in the documentation of the
+''Element Types Configurations'' model.
 
 ===How to do it?===
 When you create a plug-in containing an element types file, you can validate this one with the validation toolsmiths.
@@ -58,7 +110,7 @@ The result is display in the ''''Problems'''' view and are categorized by the ty
 
 Like others problems, you can double-click on one to open the concerning file. You can delete problem too when you think it is managed.
 
-==Architecture plug-in validation==
+==Architecture Plug-in Validation==
 ===What is checked?===
 To validate an architecture plug-in, we have some points to check. Here are the checked points:
 * Validation of the needed dependencies: '''ERROR'''