Custom Documentation

LieberLieber Embedded Engineer uses a default file header and the class/operation notes to generate documentation in form of comments for your source code. These comments will also be extended by the information of linked Requirements (realization and trace).

If a custom documentation tagged value from the CustomDocumentation Stereotype is found, Embedded Engineer will omit the generation of the Notes field as comments and will only write out the custom documentation. This stereotype can be added to any level on a Package and/or Class.

The configured CustomDocumentation: FileHeader, MethodHeader and/or FieldHeader will be inherited to any subpackage and element and can also be overwritten on any subpackage/-element level.

Info

The Notes field was improved to remove all RTF/Html tags and return pure strings.

Links to websites and files will still show the original Url/filepath.

Lists will be prefixed with a hyphen to indicate the list elements

Notes

generated comment

/* ****************************************************
* This is a Comment contains:
* Colors: red blue green
* Styles: bold italic underlined and all combined
*
*  - list1
*  - list 2 with all Styles
*  - list3
*  - NumList
*  - NumList2 with all Styles
*  - NumList3
*
* Hyperlink: www.lieberlieber.com = Hyperlink
* File: C:\tmp\tmp.txt
* ****************************************************
*  */

Available information

To generate the comments/documentation for the headers we use use the Documentation Object Model below. This information is accessible via three documentation objects and SmartFormat.NET, a lightweight template library.

Note

Note that no comment characters such as // or /* .. */ need to be used in the Tagged Value since these will be automatically generated.

Object Model Overview

FileHeader

You can access the following objects and properties of the FileHeader directly with SmartFormat.NET.

Name	Description	Type
ModelPath	The system file path to the model from which the code was generated	string
ElementPath	The model path to the generated element	string
DateTime	The current date and time	DateTime
Author	The author of the element generated	string
ModelElement	The UML object itself from which the code was generated	UML object
Notes	The elements notes/documentation from the model	string

Example

Tagged Value

***************************************************
Model File: {ModelPath}
Model Path: {ElementPath}
{DateTime:yyyy-MM-dd  - HH:mm}
***************************************************

generated code

/* ****************************************************
*  Model File: C:\tmp\CodeGenerationComponentsTest.EAP
*  Model Path: Model.EmbeddedEngineer_Components.AnsiC.Structural_Elements.Classes.ClassTest
* 
*  2017-09-04  - 09:39
* ****************************************************
*  */

MethodHeader

You can access the following objects and properties of the MethodHeader directly with SmartFormat.NET.

Name	Description	Type	Type Description
Classification	The reference type classification	TypeClassification	TypeClassification
IsStatic	Shows if the operation is static	boolean
Modifier	The operation modifiers	Modifier	Modifier
ModifierList	The operation modifiers listed	string collection
Modifiers	Simple space joined string of ModifierList	string
Name	Name of the operation (as shown in the model)	string
FullName	Name as generated by Embedded Engineer	string
Parameters	Collection of the parameters for the operation	Collection	Parameter
Preamble	FunctionPreamble defined TaggedValue	string	Function Preambles
ReturnType	Return type of the operation	ITypeDocumenation	TypeDocumenation
ModelElement	The UML object itself from which the code was generated	Uml object	UML object
Notes	The operations notes/documentation from the model	string

Example

Tagged Value

Name:       {Name}
Returns:    {ReturnType}
Parameters: {Parameters:list:{}|, |, }

generated code

/* Name:        FncPublic
* Returns:     int
* Parameters:   bool paramBool,  int paramInt,  byte paramByte,  char paramChar,  double paramDouble,  int* paramRef
*  */

Parameters

You can access the following objects and properties of the Parameters directly with SmartFormat.NET.

Name	Description	Type	Type Description
Classification	Contains reference type classification	TypeClassification	TypeClassification
Type	Type of the parameter	ITypeDocumenation	TypeDocumenation
DefaultValue	The default value set in the model	string
Direction	The parameter direction	string	e.g.: in, out, inout,...
Name	The name of the parameter	string
Qualifier	Type qualifier of the parameter	TypeQualifier	TypeQualifier
ModelElement	The UML object itself from which the code was generated	Uml object	UML object
Notes	The parameter notes/documentation from the model	string

Info

By default there is also a simple .ToString() implementation for Parameter which will return ... Direction Type Name and DefaultValue.

FieldHeader

You can access the following objects and properties of the FieldHeader directly with SmartFormat.NET.

Name	Description	Type	Type Description
Classification	Contains reference type classification	TypeClassification	TypeClassification
Classifier	The classifier documentation if the type referes to a model internal element	IClassifierDocumentation	ClassifierDocumentation
Containment	The classification as string	string
Type	Type of the attribute	ITypeDocumenation	TypeDocumenation
DefaultValue	The default value set in the model	string
IsArray	Shows if the attribute has an upper bound set	bool
ArraySize	The size of the array	string
Name	The name of the parameter	string
Qualifier	Type qualifier of the parameter	TypeQualifier	TypeQualifier
ModelElement	The UML object itself from which the code was generated	Uml object	UML object
Notes	The parameter notes/documentation from the model	string

SubTypes

TypeDocumenation

Name	Description	Type	Type Description
Classification	Contains reference type classification	TypeClassification	TypeClassification
Containment	The classification as string	string
ModelElement	The UML object itself from which the code was generated	Uml object	UML object
Name	The name of the type	string

ClassifierDocumentation

Name	Description	Type	Type Description
Classification	Contains reference type classification	TypeClassification	TypeClassification
Containment	The classification as string	string
Name	The name of the type	string
IsStatic	Is the classifier static	bool
IsSingleton	Is the classifier a singleton	bool
IsStruct	Is the classifier a struct	bool
ModelElement	The UML object itself from which the code was generated	Uml object	UML object
Notes	The parameter notes/documentation from the model	string

Modifier

enum Modifier
{
    None = 0,
    Private = 2,
    Protected = 4,
    Public = 8,
    Internal = 16,
    ProtectedInternal = 32,
    Package = 64,
    Singleton = 128,
    Define = 256,
    Constructor = 512,
    Typedef = 1024,
    Parameter = 2048,
    Readonly = 4096,
    Destructor = 8192,
    Pure = 16384,
    Virtual = 32768,
    IsQuery = 65536,
    Inline = 131072,
    Const = 262144
}

TypeQualifier

enum TypeQualifier
{
    Const = 1,
    Volatile = 2,
    Out = 4
}

TypeClassification

enum TypeClassification
{
    ValueType,
    ReferenceType,
}