ecore-doc-context-builder

Ecore documentation context builder resolves logical names of Ecore model elements to links to ecore model documentation generated by generate documentation ecore command. In model-driven development based on EMF Ecore it simplifies writing technical documentation and referencing of model documentation from generated content.

In other words, it allows to write documentation in terms of model elements, i.e. the model documentation can be though as “dictionary” of a “ubiquitous language” defined as EMF Ecore models.

Examples

In the below examples the ecore documentation context builder was mounted under ecore-doc/ prefix.

EPackage

Token Interpolation
${ecore-doc/ncore} ncore
${ecore-doc/ncore Ncore} Ncore
${ecore-doc/non-existent-package|Non existent package with default token value} Non existent package with default token value

EClass

Token Interpolation
${ecore-doc/vinci-app/ActionBase} ActionBase
${ecore-doc/vinci-app/ActionBase Action Base} Action Base

EAttribute

Token Interpolation
${ecore-doc/vinci-app/ActionBase.activator} ActionBase.activator
${ecore-doc/vinci-app/ActionBase.activator action activator} action activator

EReference

Token Interpolation
${ecore-doc/vinci-app/ActionBase:content} ActionBase.content
${ecore-doc/vinci-app/ActionBase:content action content} action content

EOperation

Token Interpolation
${ecore-doc/vinci-app/BootstrapContainerApplicationBuilder#EOperation-createApplicationBuilderSupplier-978b17ea4dfe41ec4562d0ce7f4eaa16b83bc0a4e3250ba83665d93d4b799507 createApplicationBuilderSupplier()} createApplicationBuilderSupplier()

Token specification

As any interpolation token the Ecore documentation token consists of a key and an optional default value ${<key>[|<default value>]}. They key has the following structure: [<prefix>]<EPackage alias>/<EClassifier name>[<member separator><member spec>][ <alternative text>], where:

  • prefix - context mount prefix, e.g. ecore-doc/
  • EPackage alias - logical name mapping to the model documentation base URL and EPackage namespace URI.
  • EClassifier name - name of an EClassifier in the EPackage identified by the EPackage alias.
  • Optional member (EStructuralFeature or EOperation) specification:
    • Member separators:
      • . for EAttributes
      • : for EReferences
      • # for EOperations
    • Member spec:
      • Name for EAttributes and EReferences
      • Encoded signature for EOperations. It can be obtained from the generated model documentation by copying EOperation link URL from the EClass list of contents and retaining the fragment part.
  • Alternative text - any text after a space will be used as a link text. If not specified, then EClassifier name is used for EClasses and EClass name dot member spec is used for EClass members.

In the case of Ecore documentation context builder the default value is used only when EPackage alias is not found in the context builder configuration. Specifying a non-existing EClassifier name will result in a broken link.

Configuration

The context builder is configured with a map of aliases to a map containing two keys:

  • base - Base URL. The URL’s are interpolated and then resolved against the context URI.
  • namespace-uri - EPackge namespace URI.

Example:

mounts:
    ecore-doc/:
        id: org.nasdanika.vinci.cli/ecore-doc-context-builder
        config:
            ncore:
                base: reference/model-doc/
                ns-uri: urn:org.nasdanika.ncore
            vinci-html:
                base: reference/model-doc/
                ns-uri: urn:org.nasdanika.vinci.html
            vinci-bootstrap:
                base: reference/model-doc/
                ns-uri: urn:org.nasdanika.vinci.bootstrap
            vinci-app:
                base: reference/model-doc/
                ns-uri: urn:org.nasdanika.vinci.app
            vinci-components:
                base: reference/model-doc/
                ns-uri: urn:org.nasdanika.vinci.components