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 custom documentation tag was found the Embedded Engineer will omit the generation of the Notes field as comments and will only write out the custom documentation.


With version 2.2 you now have an even easier way of adding the Notes field to your custom documentation. (see: documentation property: Notes)

To use these TaggedValues simply add the CustomDocumentation Stereotype 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.

Version 2.1

These comments can now be extended and customized using the new Tagged Values:

  • FileHeader
  • MethodHeader

Both Tagged Values can be used either on packages, classes and in case of MethodHeader also on operations.
Embedded Engineer will set these headers for all child elements (e.g.: all operations in a class, all classes in a package, ...).


Version 2.2

An additional Tagged Value for fields was added:

  • FieldHeader

This Tagged Value can also be used either on packages, classes and on attributes.
Embedded Engineer will set the header for all child elements (e.g.: all attributes in a class, all classes in a package, ...).

Version 2.3

The Notes field added in Version 2.2 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 prefixe with a hyphen to indicate the list elements

/* ****************************************************
 * 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 file and method header we use use the information from the UML model.
This information is accessible via three documentation objects and SmartFormat.NET, a lightweight template library.

Themplate Engine

The custom documentation is provided via the below defined Documenation object model and will be formatted by:
SmartFormat.NET

for more information about the SmartFormat.NET Syntax please visit: SmartFormat.NET Wiki


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

Documentation object model

FileHeader

The FileHeader object contains the following properties you can directly access with SmartFormat.

NameDescriptionType
ModelPathContains the system file path to the model from which the code was generated

string

ElementPathContains the model path to the generated elementstring
DateTimeContains the current date and timeDateTime
AuthorContains the author of the element generatedstring
ElementContains the UML object itself from which the code was generatedUML object

Notes
(available in version 2.2)

Contains the elements notes/documentation from the modelstring
Example of custom FileHeader Tagged Value
***************************************************
Model File: {ModelPath}
Model Path: {ElementPath}
{DateTime:yyyy-MM-dd  - HH:mm}
***************************************************

This Tagged Value will (depending on the language selected) produce an output such as:

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

MethodHeader

The MethodHeader contains the following objects and properties you can directly access with SmartFormat.

NameDescriptionTypeType Description
ClassificationContains reference type classification

TypeClassification

Enum with values: ValueType, ReferenceType
IsStaticShows if the operation is staticboolean
ModifierContains the operation modifiersModifierModifier
ModifierListContains the operation modifiers listedstring collection
ModifiersSimple space joined string of ModifierListstring
NameName of the operation (as shown in the model)string
FullNameName as generated by Embedded Engineerstring
ParametersCollection of the parameters for the operationCollectionParameter
PreambleFunctionPreamble defined TaggedValuestringOperations - Function Preambles
ReturnTypeReturn type of the operationITypeDocumenationTypeDocumenation
ModelElementContains the UML object itself from which the code was generatedUML object

Notes
(available in version 2.2)

Contains the operations notes/documentation from the modelstring
Example of custom MethodHeader Tagged Value
Name:		{Name}
Returns: 	{ReturnType}
Parameters:	{Parameters:list:{}|, |, }

This Tagged Value will (depending on the language selected) produce an output such as:

Example of custom MethodHeader output
/* Name:		FncPublic
 * Returns: 	int
 * Parameters:	 bool paramBool,  int paramInt,  byte paramByte,  char paramChar,  double paramDouble,  int* paramRef
 *  */

Parameters

The MethodHeader objects contain a collection of parameters. The following properties are available for these parameters.

NameDescriptionTypeType Description
ClassificationContains reference type classification

TypeClassification

Enum with values: ValueType, ReferenceType
TypeType of the parameterITypeDocumenationTypeDocumenation
DefaultValueContains the default value set in the modelstring
DirectionContains the parameter directionstringe.g.: in, out, inout,...
NameContains the name of the parameterstring
QualifierType qualifier of the parameterTypeQualifier Enum with values: Const, Volatile, Out
ModelElement
(available in version 3.1)
Contains the UML object itself from which the code was generatedUML object

Notes
(available in version 2.2)

Contains the parameter notes/documentation from the modelstring

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


FieldHeader

(available in version 2.2)

The FieldHeader contains the following objects and properties you can directly access with SmartFormat.

NameDescriptionTypeType Description
ClassificationContains reference type classification

TypeClassification

Enum with values: ValueType, ReferenceType
ClassifierContains the classifier documentation if the type referes to a model internal element

IClassifierDocumentation

ClassifierDocumentation
ContainmentContains the classification as string

string


TypeType of the attributeITypeDocumenationTypeDocumenation
DefaultValueContains the default value set in the modelstring
IsArrayShows if the attribute has an upper bound setbool
ArraySizeThe size of the arraystring
NameContains the name of the parameterstring
QualifierType qualifier of the parameterTypeQualifier Enum with values: Const, Volatile, Out
ModelElementContains the UML object itself from which the code was generatedUML object

Notes

Contains the parameter notes/documentation from the modelstring


SubTypes

TypeDocumenation

NameDescriptionTypeType Description
ClassificationContains reference type classification

TypeClassification

Enum with values: ValueType, ReferenceType
ContainmentContains the classification as string

string


ModelElementContains the UML object itself from which the code was generatedUML object
NameContains the name of the typestring


ClassifierDocumentation

NameDescriptionTypeType Description
ClassificationContains reference type classification

TypeClassification

Enum with values: ValueType, ReferenceType
ContainmentContains the classification as string

string


NameContains the name of the typestring
IsStaticIs the classifier static

bool


IsSingletonIs the classifier a singletonbool
IsStructIs the classifier a struchtbool
ModelElementContains the UML object itself from which the code was generatedUML object
NotesContains the parameter notes/documentation from the modelstring


Modifier enum description
public 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
}