TIP Doc Generator DocStructure
JOSIF Main Page | JOSIF Framework |TIP Doc Generator | TIP Doc Generator Doc Structure
Terminology and Convention
Terminology
Convention
Structure of Generated TIP Doc
This page describes the structure of generated TIP doc. We will take the documents generated from TIP SPM Model and TIP Test Models as examples. Please note that the examples only reflect status of the models and the generator at the time the page is compiled.
The TIP doc generated by TIP Documentation Generator consists of following parts:
- a Cover Page
- a Notice about TMF and the doc
- Chapter 1: Introduction of the TIP specification.
- Chapter 2: Summary of the TIP specification
- Chapter 3: Detailed information of the nformation Model of the specification
- Chapter 4: Detailed information of the Service Interfaces of the specification
- Header and Foot of the pages
Cover Page
Let's look at a sample of the cover page, then we give details of each components of the page.
Sample of Cover Page
The cover page of document of TIP SPM Model.
title
pattern:
'${fileName}, ${serviceName} Information Agreement'
where ${fileName} is the value of fileName variable, ${serviceName} is the value of serviceName variable. The values are given by authors of TIP models.
sample:
This title of the TIP SPM document is like this : 'TIP_SPM_IA, Service Problem Management Information Agreement'
version
pattern:
'Version ${Version}'
where ${Version} is the version of tigerstripe model, the value of <version>: element in tigerstripe.xml of a TIP model project.
sample:
The document of TIP SPM model can have this version: 'Version 0.0.3'
TMF logo
TMF logo is put at the right-buttom of cover page and in header of every normal pages, with scale percent 30.
This is TMF Logo in scale percent 100:
Date of the Doc
Pattern:
'Month Year', it is the date when the doc is generated. Here Month is 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', and 'December'. Year is 4-digits representation of a year, e.g. '2010'
sample:
If a doc is generated by the doc generator at September, 2009, then the date will be 'April 2010'.
Notice
Here is a sample of the Notice page of TIP Doc. It is the notice in the document of TIP SPM Model. All documents of TIP Model will have the same notice page.
The content of the notice is give at tigerstripe.xml of the model project.
Copyright 2010 TM Forum
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an 'AS IS' BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Chapter 1: Introduction
The title of the chapter 1 of the generated doc is 'Introduction'. This chapter gives introduction to the specifications, including the domain of the specification focused, the needs to meet, the relationship with other specifications inside or ouside TMF.
Here is a sample. It is the chapter 1 of a document generated from TIP SPM Model.
Note that for some reason, in the introduction chapter and summary chapter, the section numbers are not automatically generated, but given by the doc author. Following shows how the number of the section "Document Structure" is given.
Chapter 2: Interface Summary
The title of the chapter 2 of the generated doc is 'Interface Summary'. This chapter gives summary of the specifications, mainly from technical point of view.
Here is a sample. It is the chapter 2 of a document generated from TIP SPM Model.
Chapter 3: Information Model
The chapter 3 of generted TIP doc has title 'Information Model'. It gives detailed information about a TIP information model.
Outline
Following is the outline of this chapter.
3. Information Model
${a paragraph gives list of packages}
3.1. Package ${fully qualified name of 1st package}
${properties and picture of the session facase}
3.1.1. Entities
3.1.1.1. ${short name of 1st entity}
${summary of the entity}
3.1.1.1.1. Attributes
${a table which describes all attributes (local or inherited) of the entity}
3.1.1.2. ${short name of 2nd entity}
${summary of the entity}
3.1.1.1.1. Attributes
${a table which describes all attributes (local or inherited) of the entity}
3.1.1.1.2. Associations
${a table which describes all associations (local or inherited) of the entity}
3.1.1.3. ...
3.1.2. Association Classes
3.1.2.1. ${short name of 1st association class}
${summary of the association class}
3.1.2.1.1. Ends
${a table which describes all ends of the association class}
3.1.2.1.2. Attributes
${a table which describes all attributes (local or inherited) of the association class}
3.1.2.2. ...
3.1.3. Data Types
3.1.3.1. ${short name of 1st datatype}
${summary of the datatype}
3.1.3.1.1. Attributes
${a table which describes all attributes (local or inherited) of the datatype}
3.1.3.2. ${short name of 2nd datatype}
${summary of the datatype}
3.1.3.2.1. Attributes
${a table which describes all attributes (local or inherited) of the datatype}
3.1.3.3. ...
3.1.4. Exceptions
3.1.4.1. ${short name of 1st exception}
${summary of the exception}
3.1.4.1.1. Attributes
${a table which describes all attributes (local or inherited) of the exception}
3.1.4.2. ${short name of 2nd exception}
${summary of the exception}
3.1.4.2.1. Attributes
${a table which describes all attributes (local or inherited) of the exception}
3.1.4.3. ...
3.1.5. Notifications
3.1.5.1. ${short name of 1st notification}
${summary of the notification}
3.1.5.1.1. Attributes
${a table which describes all attributes (local or inherited) of the notification}
3.1.5.2. ${short name of 2nd notification}
${summary of the notification}
3.1.5.2.1. Attributes
${a table which describes all attributes (local or inherited) of the notification}
3.1.5.3. ...
3.1.6. Enumerations
3.1.6.1. ${short name of 1st enumeration}
${summary of the enumeration}
3.1.6.1.1. Literals
${a table which describes all literals(local) of the enumeration}
3.1.6.2. ${short name of 2nd notification}
${summary of the enumeration}
3.1.6.2.1. Literals
${a table which describes all literals(local) of the enumeration}
3.1.6.3. ...
Note that we have sub-section about 'Entities' only if there is at least one entity belong to this package. The same rule is applied for other kinds of artifacts.
Here is the content table of the chapter 3 of TIP Test1 Model document.
List of packages
At the very beging of the chapter, we give a list of all packages which are available from the service and non-empty (i.e. contains at least one artifact of following type: entity, datatype, association, association class, exception, enumeration, and notification). The pattern of the paragraph is:
List of packages which are available from ${serviceName} and contain artifacts:
- ${short name of 1st package with a link to corresponding section entitled the short name}
- ${short name of 2nd package with a link to corresponding section entitled the short name}
- ...
If no such package available in the TIP Model, the paragraph reads
no packages available from ${serviceName}.
Here is a sample from document of TIP SPM Model.
List of packages which are available from Service Problem Management and contain artifacts: - org.tmforum.tip.cbe.problem - org.tmforum.tip.service.problem
In this chapter, for each non-empty package, we have a sub-section which gives detailed information about the package. The information consists of following parts:
1) Entities
if there is at lease one entity in this package, we will have a section entitled 'Entities', and there is a sub-section for each entities.
No such section if no any entity in this package.
2) Association Classes
if there is at lease one association class in this package, we will have a section entitled 'Association Classes', and there is a sub-section for each association class.
No such section if no any association class in this package.
3) Datatypes
if there is at least one datatype in this package, we will have a section entitled 'Datatypes', and there is a sub-section for each datatype.
No such section if no any datatype defined in this package.
4) Exceptions
if there is at least one exception in this package, we will have a section entitled 'Exceptions', and there is a sub-section for each exception.
No such section if no any exception defined in this package.
5) Notifications
if there is at least one notification (original or generated) in this package, we will have a section entitled 'Notifications', and there is a sub-section for each notification.
No such section if no any notification defined in this package.
6) Enumerations
if there is at least one enumeration in this package, we will have a section entitled 'Enumerations', and there is a sub-section for each enumeration .
No such section if no any enumeration defined in this package.
Details of Entities
Each section dedicated to an entity includes following contents:
1) summary (description and some properties)
2) table of attributes
3) table of association ends
Pattern of the summary:
- Type: Entity Artifact
- Package: ${fully qualified name of package of entity}
- All super types:
${firstSuperType}
${secondSuperType}
....
- Description: ${description}
- Properties:
isAbstract = ${value of isAbstract}
isMandatory = ${value of tipClass:support}
isExtendable = true
objectCreationNotification = ${value of tipClass:objectCreationNotification}
objectDeletionNotification = ${value of tipClass:objectDeletionNotification}
objectDiscoveryNotification = ${value of tipClass:objectDiscoveryNotification}
${picture of the entity}
Note that the "All super types" will appear only if there is at least one supertype, explicitly or implicitly. Where an explicit supertype is the one declared in the model, and the implicit supertype is the one defined in Internal Framework Model. For example, org.tmforum.tip.internal.entity.EntityBase is the implicit supertype for every entity. Texts in green color indicate implicit data.
Pattern of table of attributes:
The table shows all attributes of the artifact. There are 3 types of attributes:
1) local attributes. These attributes are shown on white background
2) attributes inherited from explicit supertypes. These attributes are shown on lavender background
3) implicit attributes which are inherited from implicit supertypes. These attributes are shown on green background
The table consists of 4 columns, called name, datatype, properties, description. For each attribute, we have one row and we use different color to distingush the local attributes from inherited).
- The 1st cell of the row is: ${the short name of the attribute}
- The 2nd cell of the row is: ${the short name of type of the attribute, with a link if its type is internal}
- the 3rd cell of the row is a list properties, its pattern is (please refer to "display rules" for more details):
typeMultiplicity = ${multiplicity of the argument}
isReadonly = ${value of isReadonly}
isOrdered = ${value of isOrdered}
isUnique = ${value of isUnique}
default value = ${default value of the attribute}
isInvariant = ${value of tipAttribute:isInvariant}
notificationDefinition = ${value of tipAttribute:notificationDefinition}
passedById = ${value of tipAttribute:passedById}
support = ${value of tipAttribute:support}
Note that if the attribute is not annotated with tipAttribute,then the last 4 will not appear.
- the 4th cell of the row is: ${description of the attribute}
Pattern of table of association ends:
One table, has 4 columns, named name, datatype, properties, description; for each applicable* navigable end, we have one row (note that we use different color to distingush local end from inherited).
- The 1st cell of the row is: ${the short name of the end}
- The 2nd cell of the row is: ${the short name of type of the end, with a link if its type is internal}
- the 3rd cell of the row is a list properties, its pattern is (please refer to "display rules" for more details):
multiplicity = ${multiplicity of the end}
aggregation = ${value of aggregation}
isNavigable = ${value of isNavigable}
isOrdered = ${value of isOrdered}
isUnique = ${value of isUnique}
isInvariant = ${value of tipAttribute:isInvariant}
notificationDefinition = ${value of tipAttribute:notificationDefinition}
passedById = ${value of tipAttribute:passedById}
support = ${value of tipAttribute:support}
association = ${short name of association to which the end belongs}
Note that if the end is not annotated with tipAttribute, then the last 4 will not appear.
- the 4th cell of the row is: ${description of the association to which the end belongs}
Sample
TIP SPM Model, Entity org.tmforum.tip.cbe.problem.Problem:
Details of Association Class
Each section dedicated to an association class includes following contents:
1) summary (description and some properties)
2) table of ends
3) table of attributes
Pattern of association class summary:
- Type: Association Class Artifact
- Package: ${fully qualified name of package}
- All super types:
${a list of supertypes}
- Description: ${description}
- Properties:
isAbstract = ${value of isAbstract}
support = ${value of tipAssociationClass:support}
objectCreationNotification = ${value of tipClass:objectCreationNotification}
objectDeletionNotification = ${value of tipClass:objectDeletionNotification}
objectDiscoveryNotification = ${value of tipClass:objectDiscoveryNotification}
Pattern of table of association ends:
same with the table of association ends of an entity.
Pattern of table of attributes:
same with the table of attributes of an entity.
Sample
TIP Test1 Model, Association class org.tmforum.tip.cbe.test.TestAssociatedWithServiceTestProblem.
Details of Datatypes
Each section dedicated to a datatype includes following contents:
1) summary (description and some properties)
2) table of attributes
Pattern of datatype summary:
- Type: Datatype Artifact
- Package: ${fully qualified name of package}
- All super types:
${a list of supertypes}
- Description: ${description}
- Properties:
isAbstract = ${value of isAbstract}
isExtendable = ${value of tipDatatype:isExtendable}
Pattern of table of attributes:
same with the attrribute table of entity.
Sample
TIP SPM Model, datatype org.tmforum.tip.cbe.problem.Comment.
Details of Exceptions
Each section dedicated to an exception includes following contents:
1) summary (description and some properties)
2) table of attributes
Pattern of exception summary:
- Type: Exception Artifact
- Package: ${fully qualified name of package}
- All super types:
${list of super types}
- Description: ${description}
- Properties:
isAbstract = ${value of isAbstract}
Pattern of table of attributes:
same with the attrribute table of entity. Note that its attributes consist of the local attributes, inherited attributes, and the attributes injected from TIP internal ExceptionBase (a link to JOSIF guidebook to be added).
Sample
TIP Test1 Model, org.tmforum.tip.cbe.test.TestFailureWithData
Details of Notifications
Each section dedicated to a notification includes following contents:
1) summary (description and some properties)
2) table of attributes
Pattern of notification summary:
- Type: Event Artifact
- Package: ${fully qualified name of package}
- All super types:
${list of super types}
- Description: ${description}
- Properties:
isAbstract = ${value of isAbstract}
support = ${value of tipNotification:support}
Pattern of table of attributes:
same with the attrribute table of entity. Note that its attributes consist of the local attributes, inherited attributes, and the attributes injected from TIP internal NotificationBase (a link to JOSIF guidebook to be added).
Note: Some notifications are generated from entities. Each the notification is of one of following type: Object Creation, Object Deletion, Object Discovery, Attribute Value Change.
Sample
TIP Test1 Model, notification org.tmforum.tip.service.test.TestEvent2.
Details of Enumerations
Each section dedicated to an enumeration includes following contents:
1) summary (description and some properties)
2) table of literals
Pattern of enumeration summary:
- Type: Enumeration Artifact
- Package: ${fully qualified name of package}
- All super types:
${list of super types}
- Description: ${description}
- Properties:
isAbstract = ${value of isAbstract}
isExtendable = ${value of tipDatatype:isExtendable}
Pattern of table of literals:
One table, has 4 columns, named name, datatype, properties, description; for each literal, we have one row:
- The 1st cell of the row is: ${the short name of the literal}
- The 2nd cell of the row is: ${the short name of type of the literal, typically, it is 'string'}
- the 3rd cell of the row is a list properties, its pattern is:
value = ${value of literal}
- the 4th cell of the row is: ${description of the literal}
Sample
TIP SPM Model, enumeration org.tmforum.tip.cbe.problem.AckStatus.
Chapter 4: Service Interfaces
The chapter 4 of generted TIP doc is named 'Service Interfaces', it gives detailed information about service interfaces provided in a TIP specification.
Outline
Outline of this chapter ....
4. Service Interfaces
${a paragraph gives list of service interfaces}
4.1 ${short name of 1st session facade}
${properties and picture of the session facase}
4.1.1 ${short name of the 1st operation in the session facade}
4.1.1.1 Arguments
${a table which describes all arguments of the operation}
4.1.2 ${short name of the 2nd operation in the session facade}
4.1.1.2 Arguments
${a table which describes all arguments of the operation}
4.1.3 ...
4.2 ${short name of 2nd session facade}
....
Here is outline of the chapter 4 of TIP SPM Model document.
List of service interfaces
In very beging of the chapter, we give a list of all service interfaces available from the service. The pattern of the paragraph is:
List of service interfaces available from ${serviceName}:
- ${short name of 1st session facade with a link to corresponding section entitled the short name}
- ${short name of 2nd session facade with a link to corresponding section entitled the short name}
- ...
If no service facade available in the TIP Model, the paragraph reads
no service interface available from ${serviceName}.
Here is a sample from document of TIP SPM Model.
List of service interfaces available from Service Problem Management: - ProblemInterface - ServiceProblemInterface
In this chapter, for each session facade, we have a sub-section which gives information about the session facade. The information consists of 2 parts:
1) summary of an interface (session facade)
It is a paragraph.
2) Method Details
For each method, we have a sub-sub-section devoted to describe method in detail.
summary of an interface
Pattern:
- Type: Session Artifact
- Package: ${the package of the session facade and a link to a section which gives details of the package (and enclosed artifacts)}
- Description: ${description of the session facade}
- Services exposed:
${list of short names of local methods and links to sub-sub-sections which give details of the methods}
- Managed entities:
${entities managed by the session facade and links to sections which give details of the entities}
- Properties:
isAbstract = ${the value of isAbstract}
${picture of the session facade}
Sample:
TIP SPM Model has an interface (session facade) ProblemInterface, its fullly qualified name is org.tmforum.tip.cbe.problem.ProblemInterface. The summary of this interface is (note that the links exist but not shown here):
Method Details
Each sub-sub-section dedicated to a method include following contents:
1) method summary (description and some properties)
2) table of arguments
Pattern of method summary (refer to "display rules" for more details):
- Description: ${description}
- Properties:
visibility = ${value of visiblity}
isAbstract = ${value of isAbstract}
support = ${value of tipOperation:support}
isIdempotent = ${value of tipOperation:isIdempotent}
bulkTransferPattern = ${value of tipOperation:bulkTransferPattern}
emitEvents = ${value of tipOperation:emitEvents}
isOneWay = ${value of tipOperation:isOneWay}
isExtendable = ${value of tipOperation:isExtendable}
- Return:
${return}
- Exceptions:
${list of short names of declared exceptions with links}
${list of short names of pre-defined exceptions with links}
Note that the pre-defined exceptions are showen in green backgroud.
Pattern of table of arguments:
One table, has 4 columns, named name, datatype, properties, description; for each argument, we have one row.
- The 1st cell of the row is: ${the short name of the argument}
- The 2nd cell of the row is: ${the short name of type of the argument, with link to internal type}
- the 3rd cell of the row is a list properties, its pattern is (refer to "display rules" for more details):
typeMultiplicity = ${multiplicity of the argument}
direction = ${direction of the argument}
passedById = ${value of tipParameter:passedById}
isBulkPotential = ${value of tipParameter:isBulkPotential}
support = ${value of tipParameter:support}
defaut value = ${default value of the argument}
isOrdered = ${value of isOrdered}
isUnique = ${value of isUnique}
- the 4th cell of the row is: ${description of the argument}
Sample
TIP SPM Model, interface org.tmforum.tip.cbe.problem.ProblemInterface, operation acknowledgeProblems:
Header and Foot
Pattern of Header: doc title, TMF logo
sample:
Pattern of Footer: doc short name and version,TMF copyright, Page number
sample:
