This is a small utility for generating HTML or LaTeX documentation from Eclipse Modeling Framework metamodels (Ecore files).
The generator uses the structure of the metamodel and the values of the GenModelDoc annotation for creating content.
The generated text will include a section for the main package in the metamodel and subsections for the classifiers, datatypes and enumerations.
This tool can be used on Xtext langues too (.xtext files). A documentation of the xtext language with links and tooltips is generated before the metamodel documentation.
In the runtime editor documentations from the metamodel appear in keyword hovers and content assists. Javadoc-like comments are parsed as documentation and are shown for reference hovers and content assists.
Once you installed the two plugins into your Eclipse (or started a runtime Eclipse with them included), just right-click on any .ecore file in your workspace and select "Generate Latex Documentation" or "Generate HTML Documentation" from the menu. As a result a .tex or .html file will be created in the same folder.
To add documentation to your metamodel, you can either use the Ecore Diagram Editor and input the textual descriptions into the "GenModel Doc" field that can be found on the Properties view, or simply add an EAnnotation to any element with the source attribute set to http://www.eclipse.org/emf/2002/GenModel and add a details entry with the key set to documentation and the value containing your description.
Alternatively, you can activate the "Ecore Documentation" view, and enter content directly through that (to use it, first select an Ecore element in the editor, and then click into the view).
We also provide validators based on EMF-IncQuery (http://eclipse.org/incquery) that provide auto-refresh validator for missing/zero-length documentation fields, gradually guiding you to complete documentation nirvana :) See the annotated screenshot below for details.
For the xtext runtime editor additions bind the following classes in your UIModule:
- MyEObjectDocumentationProvider.class -> documentation from EMF model/xtext comments
- MyEObjectHover.class -> hovers for keywords
- MyProposalProvider.class -> content assist for keywords
The generator supports documentation formatted in Markdown syntax. You can use any Markdown element you like.
The generator supports a subset of Markdown syntax:
- building lists
- emphasis of text elements (bold/italic/underline)
- hyperlinks to remote URLs
The output format is customizable via CSS. The style-sheet is assumed to be in the same directory as the generated HTML file, and is assumed to be called style.css. An example CSS file can be found in the resources folder of the repository.
At least the following packages need to be imported in your LaTex document for the documentation to be valid:
\usepackage{color}
\usepackage{hyperref}
\usepackage{tabularx}
\usepackage{float}
The following is a short description of the structure used in documenting the metamodels.
The documentation section of each metamodel begins with a short introduction explaining the rationale behind the given metamodel and lists the main concepts that are identified and represented by the elements in the metamodel. This introduction is stored in the main EPackage that contains the elements of the metamodel. Finally, the namespace prefix and URI used when persisting instance models of the metamodel are listed.
After the metamodel introduction, each element in the Package has a subsection which starts with the description of the element, followed by various element properties and tables depending on the type of the element.
There are two properties and three tables that can appear for an EClass element. The Abstract property specifies that instance models cannot contain EObjects that are instances of this EClass, instead subtypes should be used. The Interface property specifies that no implementation is generated for the EClass. Finally, the list of Supertypes is given.
The tables list the (i) attributes, (ii) references and (iii) operations of the EClass, if there are any. Each table has three columns, the first contains the name of the element (colored blue if derived), the second a list of properties and the third any documentation that is given. Apart from clarifications and rationale, this documentation part can also include validation rules that should be satisfied by instance models (with violations appearing as either errors or warnings).
Some properties are common to the tables, these are the Type (T) and the Cardinality of the element and whether the values are Unordered or Not unique (the default values Ordered and Unique are not shown). In the case of operations, the type and cardinality refers to the return value.
The properties specific to features (attributes and references) are Non-change-able (cannot be modified directly), Volatile (value not stored in a field), Transient (value not persisted), Unsettable (has Unset value) and Derived (value is computed), again, only non-default values are listed.
The property specific to attributes is Identifier, which is true if the value of the attribute identifies the EObject.
The reference-specific properties are Opposite (Op) (the name of the reference in the target that will refer back to the source), Containment (true, if target EObject of this reference is persisted inside source) and Container (Containment is true for opposite of reference). Finally, the property specific to operations is Parameters (any number of parameters with type and cardinality).
There is only one table that appears additionally to the element description. The table lists the literals of the EEnum and contains three columns, the name, value and documentation of the literal.
All code in this repository is available under the Eclipse Public License v1.0: http://www.eclipse.org/legal/epl-v10.html