How to format descriptions

Warning

This page is under construction.

To contribute or participate contact support@boost-lab.net

Overview

The format to be used for descriptions is common across the SysML model.

Summary of Supplementary Directives

The WG12 Review Checklist (QCN265) states “204. The definition of each EXPRESS/SysML construct is unambiguous and understandable, grammatically correct, and defines the concept (not simply restates the EXRESS/SysML)”.

See Supplementary Directives for the official directives.

See also Naming.

The following are a summary of the directives.

Text in General

The following table summarises the do’s and dont’s for the text of descriptions and definitions.

do use...	don’t use...	see also
“instances of <entity name>”	plural e.g. <entity name>s	6.4.9.4 Plurals of
“shall” “shall not”	“is required to” “only...is permitted” “must” “most not”	4.8 Acceptable wording
“should” “should not”	“is recommended that...” “ought to...”	4.8 Acceptable wording
“may” “need not” (i.e. permissable in limits of standard)	“is permitted” “is allowed”	4.8 Acceptable wording 4.8 Acceptable wording
“can” “cannot” (i.e. something that is possible)	“to be able to” “it is possible to”	4.8 Acceptable wording
<note></note> ot “that is”	“i.e.”	4.8 Acceptable wording
<example></example>	“e.g.” “etc” (“for example” )	4.8 Acceptable wording
	and/or	4.10 Words to avoid
datum <xyz>s (e.g. datum points)	datums	4.10 Words to avoid
use	utilise	4.10 Words to avoid
that is	which is	4.11 Frequently used words
data are	data is	4.11 Frequently used words
between = 2 among = 2 or more than 2		4.11 Frequently used words
better english examples are: ”...to which XYZ belongs.” ”...with which the XYZ is associated.” ”...the XYZ used to refer to the ABC.”	sentences ending in “at” “to” “with” “from” “of” “on” ”...that XYZ belongs to.” ”...the XYZ is associated with.” ”...the XYZ by which the ABC is referred to.”

Tip

Care should be taken with Carridge-Return (
) and Line-Feed (
)as both these will introduce a new paragraph in the documentation for the standard.

Different SysML tools will use the characters differently, so when porting models between tools what was visible as a new line in one tool may appear differently in another.

Important

If using any of the tags described below, the result must be well formed xml, e.g. <br/> should be used rather than <br>.

Blocks and Constraint Blocks (description)

The text should use complete sentences and shall state clearly the following:

• the concept that the entity data type represents;

• the information about the concept that is represented in the data structure and constraints defined by the entity data type;

• the phrase “an <EntityName> is/represents …” may be used as a short hand for “An instance of the <EntityName> entity data type is/represents …”

  • if this convention is used it shall be used consistenty;
  • if this convention is used, the convention itself shall be described in the introduction of the standard.

Properties and Constraints (definition)

The text is a fragment of a sentence that can be used in place of the name of the property (as done in clause 3 “Terms and Definitions”).

• All optional properties shall conclude with the sentence: The value of this attribute need not be specified.

Examples and Notes

See also 4.4.4 Examples and 4.4.3 Notes

• should come after the main text;

• can be in any order;

• should not be numbered, the number is added by the documentation scripts;

• Examples: <example>...</example>:

  • Provided to clarify the concept that is represented by the entity data type or to illustrate the population of the entity data type and its attributes. It shall be clear whether each example refers to the concept represented by the entity data type or the data that is governed by the entity data type.

• Notes: <note>...</note>:

  • information that is essential to the reader understanding the document can include references to other sources;

• for example:

  <note>This is the first note.</note>
  <note>This is the second note.</note>
  <example>This is the first example.</example>
  

Figures and Tables

See also 4.4.1 Figures and 4.4.2 Tables

• These are contained in a <figuresysml></figuresysml>, <figure></figure> or <table></table>;

• image location:

  • figure and table include a <name></name> tag that has the relative path from the Domain model html file to the image;
  • figuresysml includes an <id></id> tag that is the xmi:id of the diagram in the sysml model.

• They include text that is the table or figure label only first word capitalized;

• If they are essential to the understanding they must be referenced in the normative text of the definition so that it is itself normative.

• If they enhance but are not essential to the understanding they shall be referenced from a suitable note or example so that it is itself informative.

• for example:

  <figuresysml><id>_18_4_1_6b1022a_1570541486114_761677_40761</id>Label for the figure</figuresysml>
  <figure><name>../imagename.png</name>Label for the figure</figure>
  <table><name>../imagename.png</name>Label for the table</table>
  

Tip

The xmi:id of a diagram can be obtained using a macro. See also Load Macros for how to load a macro.

Figure 33 Run “Get UUID” macro to see the ID and the UUID

Lists

Bulleted lists use standard HTML notation of ul and li tags (see also 4.5 Lists)

• the ”;” (all but last) and ”.” (last) must be included.

• for example:

  <ul><li>first bullet;</li><li>second bullet.</li></ul>
  

Fixed hyperlinks

For hyperlinks not auto-generated from the entity and attribute names (see also 4.6 References within the text)

• These are contained in <a></a>

• They include a <path></path> tag that has the relative path from the Domain model html file to the file, or an http href,

• The include the text to be displayed.

• For Example:

  <a><path>5_main.htm#study</path>Clause 5</a> <a><path>https://www.iso.org</path>iso.org</a>.<br/>

Example

The following is an example of a formatted description where “Foo” and “Bar” are blocks in the model:

A Foo is a type of Bar that is used as a placeholder. See also <a><path>5_main.htm#study</path>internal links</a>
or <a><path>https://www.iso.org</path>external links</a>. It is has a bulleted list:<br/>
<ul><li>first bullet;</li><li>second bullet.</li></ul>
<note>This is the first note referencing a figure (see following Figure).</note>
<note>This is the second note.</note>
<example>This is the first example referecing the table which is infact an image (see following Table).</example><br>
<figure><name>sys/picturesAnnex/inverseCompositeAggregation.png</name>The title for the figure</figure><br>
<table><name>sys/script/img/tables.png</name>The title for the table</table>
<figuresysml><id>_18_4_1_6b1022a_1570541486114_761677_40761</id>Block Definition Diagram of the Activity CTC</figuresysml>

The following is an example of a property description where “Widget” is a block in the model:

specifies the Widget for the Foo. The value of this attribute need not be specified.

The following shows how the example will look in the standard

Figure 34 How the example formatted description is displayed in the documentation

Official Supplementary Directives

Important

This is an extract from the Supplementary Directives (SC4N2412) that has been updated to align with the use of SysML rather than EXPRESS. The clause numbers from the directives are included in the headings to aid navigation.

See also ISO House Style. This website includes the complete set of rules for text and formattingm, and provides navigation.

4.4.1 Figures

Figures are normative if referenced from the main text and informative if referenced only from a note, example, or informative annex. Each figure shall be identified by a number and shall have a title.

4.4.1.1 Numbering figures

(Not applicable in HTML because done by publication scripts)

4.4.1.2 Capitalizing figure titles

The first word in the title of all figures shall be capitalized. All other words in the title shall be in lower case unless they are proper names.

4.4.1.3 References to figures

All figures shall be referenced at least once in the text. The first (or only) reference to each fig-ure shall occur in the text before the figure.

EXAMPLE The following are two examples of wording that can be used to reference figures (note this cannot be obeyed because the figure number is generated by the publication script):

* … as shown in Figure 3
* … (see Figure 3)

The word “Figure” shall be capitalized in all references to figures.

If a figure is referenced solely from a note or example, the figure shall be considered a part of the note or example and thus, is informative.

4.4.2 Tables

Tables are normative if referenced from normative text (clause, subclause, or normative index) and informative if referenced only from a note, example, or informative annex. Each table shall be identified by a number and shall have a title.

4.4.2.1 Numbering tables

Tables shall be numbered with Arabic numbers beginning with 1. Except for annexes, the num-bering is independent of the numbering of clauses, subclauses, and figures. Numbers of tables in annexes shall be preceded by the letter assigned to the annex and a period. The first table in Annex A is referred to as “Table A.1”.

4.4.2.2 Capitalizing titles of tables

The first word in the title of all tables shall be capitalized. All other words in the titles shall be in lower case unless they are proper nouns.

4.4.2.3 Continuing tables

(Not applicable in HTML)

4.4.2.4 Capitalization of column headings within tables

The first word in the heading of each column of a table shall begin with a capital letter. All other words in the heading shall be in lower case unless they are proper nouns.

4.4.2.5 Repetition of column headings within a table

(Not applicable in HTML)

4.4.2.6 Units in tables

If units are used in a column of a table, they shall be indicated underneath the headings.

EXAMPLE The example below illustrates the specification of units in a table:

Widget height (mm)	Maximum velocity (m/s)
10.0	1.5
20.0	0.9

4.4.2.7 References to tables

(Not Applicable in HTML because tables are images)

4.4.3 Notes

Notes may be used to give information that is essential to the reader understanding the document.

Notes may refer to normative elements or normative references, although notes are informative (unless they are notes within a normative table or a figure). Notes may be part of any element except the cover page, the title, and footnotes.

4.4.3.1 Placement of notes

Notes shall be placed after the clause, subclause, or paragraph to which they refer.

4.4.3.2 Identification and numbering of notes

Each note shall be preceded by the title NOTE placed at the beginning of the first line of the text of the note.

If a clause or subclause contains more than one note, each note shall be preceded by NOTE <n>.

Notes shall be numbered consecutively starting at 1 within the clause or subclause. <n> is to be replaced by the number of the note. The text of each note shall follow the Arabic numeral. Do not place a period after the number of the note.

4.4.4 Examples

Examples may be used for further clarification of items such as style for mathematical notation, documentation, dates, or references. Examples are informative.

4.4.4.1 Placement of examples

Examples shall be placed after the clause, subclause, or paragraph to which they refer.

4.4.4.2 Identification and numbering of examples

Each example shall be preceded by the title EXAMPLE placed at the beginning of the first line of the text of the example.

If a clause or subclause contains more than one example, each example shall be preceded by EXAMPLE <n>. Examples shall be numbered consecutively starting at 1 within the clause or subclause. <n> is to be replaced by the number of the example. The text of each example shall follow the Arabic numeral. Do not place a period after the number of the example.

4.5 Lists

Lists may be introduced by a sentence, a complete grammatical proposition followed by a colon, or by the first part of a proposition without a colon, completed by the items in the list. Each item in the list shall be of the same gram-matical construction (that is, all sentences, all noun phrases, or all verb phrases), and shall be grammatically consistent with the text that introduces the list.

4.6 References within the text

References within the text shall be in one of the following forms (see also ISO/IEC Directives, Part 2, 6.6.7).

4.6.1 References to this International Standard

The form “ISO <ISO standard number>” shall be used only when the entire standard is being referenced; if one part of the standard is being referred to, use the following form:

• “this part of ISO <ISO standard number>“ (reference to this part only) - OUT OF DATE WITH ISO directives, use “this document”;
• “ISO <ISO standard number>-<part number>“ (reference to another part).

NOTE 1 The word “part” used by itself is used with specific domain meaning in SC 4 standards. For example, in ISO 10303 “part” refers to a manufactured object or piece part. When referring to one of the documents of an ISO standard, the wording should be “part of ISO <ISO standard number>”.

4.6.2 References to other International Standards and documents

Any publicly available document recognized by SC 4 as having wide acceptance and authorita-tive status as well as being publicly available (see ISO/IEC Directives, Part 2, 6.2.2) can be ref-erenced in an SC 4 standard. National and industry standards can be referenced; however, if there is also an ISO standard, the ISO standard shall be used.

When referring to another International Standard from normative text, use “ISO” in the text followed by the reference number; only include the part number if applicable. Give the full title in the normative references clause. References to a particular element of another International Standard shall include the clause referred to as well as the reference number of the International Standard and the date of publication. ISO Technical Specifications, Publicly Available Specifi-cations, and Technical Reports may be referenced in the same way.

If reference is made to a standard from informative text where that standard has not been given as a normative reference, the standard shall be listed in the bibliography.

4.6.3 References to subdivisions of the text

Use “clause” only to refer to an entire clause. Do not use the words “subclause” or “reference”. Use the following forms:

• in accordance with Clause 3;
• according to 3.1;
• details as given in 3.1.1;
• (see 3.1.1);
• as described in 3.1.2;
• see Annex B.

4.7 Punctuation of words in a series

When three or more words are grouped together in a series, a comma shall not follow the word that appears before the conjunction that precedes the last word in the series.

EXAMPLE “In the United States, dog-wood, cherry and redbud are three types of trees that bloom in the spring.”

4.8 Acceptable wording

This subclause gives details on the wording to be used to explain requirements and recommendations.

4.8.1 Using “shall” and “shall not”

The verbal forms “shall” and “shall not” indicate requirements to be followed to conform to the standard and from which no deviation is permitted. The words “shall” and “shall not” shall be used in normative text and shall not be used in the introduction, foreword, notes, or examples, which are informative text.

“Shall” shall be used to denote the following:

• is to …;
• is required to …;
• it is required that …;
• has to …;
• only … is permitted;
• it is necessary ….

“Shall not” shall be used to denote the following:

• it is not allowed (permitted, acceptable, permissible)...;
• is required to be not …;
• is required that … be not...;
• is not to be ….

Do not use “must” except to describe “unavoidable” situations. Do not use “may not” instead of “shall not” to express a prohibition.

NOTE To express a direct instruction, such as referring to steps to be taken in a test method, use the imperative.

For instance, “Use the imperative”.

4.8.2 Using “must” and “must not”

The words “must” and “must not” shall be used only to convey external statutory regulations.

4.8.3 Using “should” and “should not”

The words “should” and “should not” shall be used to recommend a particularly suitable possibility or course of action without excluding others.

“Should” shall be used to denote the following:

• it is recommended that …;
• ought to …;

“Should not” shall be used to denote the following:

• it is recommended that … not;
• ought not to ….

4.8.4 Use of “may” and “need not”

The words “may” and “need not” indicate a course of action that is permissible within the limits of the standard.

“May” shall be used to denote the following:

• … is permitted;
• … is allowed;
• … is permissible.

“Need not” shall be used to denote the following:

• it is not required that …;
• no … is required.

Do not use “can” instead of “may” in this context. Do not use “possible” or “impossible” in this context.

NOTE “May” refers to something that is permitted whereas “can” refers to something that is possible.

4.8.5 Use of “can” and “cannot”

The words “can” and “cannot” indicate possibility and capability.

“Can” shall be used to denote the following:

• to be able to …;
• to be in a position to …;
• there is a possibility of …;
• it is possible to ….

“Cannot” shall be used to denote the following:

• to be unable to …;
• to be not in a position to …;
• there is no possibility of …;
• it is impossible to ….

NOTE “Can” refers to something that is possible whereas “may” refers to something that is permitted.

4.8.6 Use of “i.e.”, “e.g.”, and “etc.”

Do not use “i.e.” and “e.g.”. Instead, use “that is” and “for example”. If using “that is,” the list that follows shall be all inclusive whereas “for example,” shall only list some of the possibilities and shall only appear in a note or example. Likewise, do not use “etc.”. End the series prior to the “etc.” being certain to use a serial comma before the “and” (added if not already there). To state that the series is incomplete, use “such as” at the start of the series.

4.8.7 Use of quotation marks

Quotation marks shall be used to set off words or phrases that may confuse the reader if not marked.

Double quotation marks “…” denote quoted text. Single quotation marks ‘…’ denote particular text string values.

4.8.8 Spelling

The spelling of names of organizations and their abbreviations shall be as used by those organizations in English, French, or Russian. For the text portion of the part, The Concise Oxford Dictionary of Current English shall be used for spelling.

NOTE Spelling checkers associated with word processor programs rarely, even in the “British spelling” mode, conform to the required dictionary.

Note the correct spelling of the following:

• numbers from one to nine shall be spelled out in words;
• modelling, modelled, centre, colour, coordinate, faceted, litre, metre, millimetre, neighbour, organization;

and the preferred spelling of the following:

• instantiation.

4.9 Hyphenation

In general, hyphenation should be used to improve readability and appearance. Hyphenation shall follow The Concise Oxford English Dictionary of Current English. These special terms shall be hyphenated as follows:

• non-zero;
• two-dimensional, three-dimensional (may be abbreviated as “2D” or “3D”);
• B-rep (boundary representation shall be spelled out the first time it appears in the text, fol-lowed by the abbreviation in parentheses, that is, “(B-rep)”. The term “B-rep” shall be added to the list of abbreviations;
• X-axis, Y-axis, and Z-axis.

Abbreviations shall not be divided by a line break.

4.10 Words to avoid

Avoid the use of words that are corporate trademarks. If using them is necessary, accompany the word by the trademark symbol “™” or the registered trademark symbol ® as appropriate.

EXAMPLE The title of ISO 10303-27 is “Product data representation and exchange: Implementation meth-ods: JavaTM programming language binding to the standard data access interface with Internet/Intranet exten-sions”. Since the word “Java” in this context is a trademark, it is accompanied by the symbol “™”.

Avoid the following words to provide editorial consistency:

• and/or: rather than use this form, expand the explanation and present both cases;
• datums: the plural of “datum” is “data”. If one is tempted to use “datums”, change it to “datum points” or “datum lines” or “datum planes” as the case may be;
• utilise: use “use” instead;
• “in other words”: this phrase is often used to join two alternative definitions of a term or concept: the alternative definitions should be reviewed and reconciled.

However, if a project cites another ISO standard, or broadly-accepted terminology for a given domain for a specific meaning of a prohibited term, the editor should follow the cited spelling.

4.11 Frequently used words

The following terms are used frequently in parts of SC 4 standards. To ensure editorial con-sistency, they should be used only in precisely defined contexts.

• between/among: use “between” to mean “exactly two;” use “among” to mean “two or more than two.”.
• construct(s): do not use this word without a qualifier. The term “resource constructs” is de-fined in ISO 10303-1; use it only as defined there. Any other use of “construct” should have a qualifier and appear in the definitions clause of the part first defining it.
• data: “data” is a plural noun and requires a plural verb, that is, “data are” not “data is”.
• if: if an “if” clause ends in a comma, do not follow it with the word “then”.
• part: the use of “part” may be confusing. To refer to a part of an SC 4 standard, always use “this part of ISO <ISO standard number>.” (See also 4.6.1)
• presentation: do not use “presentation” for “representation”. “Presentation” should be re-stricted to situations with visual aspects;
• schema: the plural of “schema” is “schemas”, not “schemata”;
• which: do not use “which” in place of “that”. “That” introduces a defining phrase; “which” introduces an informational phrase. See [14].

4.12 Representation of dates

All SC 4 standards shall conform to ISO 8601. In particular, all calendar dates shall be in the form yyyy-mm-dd, using the four-digit date, as prescribed in clause 5.2.1.1 of ISO 8601. Thus, the date April 26, 2001 is represented as 2001-04-26.

6.4.6 Documentation of formal propositions

Formal propositions follow the Attribute(Property) declaration (types and entity data types), the definition of enumeration items (types only), or argument definitions (rules). Formal propositions are constraints that are computable, are written in OCL and are placed within Blocks or ConstraintBlocks.

The following rules apply to formal propositions in the documentation of types (see 6.4.8), entity data types (see 6.4.9), or rules (see 6.4.10).

• The formal propositions shall be preceded by the underlined title “Formal propositions:”.
• When there is a name for the constraint, each formal proposition shall start with the name and be followed immediately by a colon and a single space. The label shall be in boldface. The colon shall not be boldface.

EXAMPLE The following examples illustrate the layout and format of formal propositions:

WR1: The value of x shall be positive.

UR1: The name shall be unique.

• The ISO required verb forms (for example, “shall” or “should” – see 4.8 Acceptable wording) shall be used. “Must” shall not be used.
• Any additional explanation or examples shall be provided as notes (see 4.4.3 Notes) or examples (see 4.4.4 Examples).
• (more in directives for EXPRESS)

6.4.7 Documentation of informal propositions

Informal propositions are un-computable constraints that cannot, or cannot reasonably, be written in OCL, although each informal proposition still represents a requirement. If a contraint exists using a natural language definition, it may be included in an informative annex as a technical discussion. Each informal proposition shall be presented as follows.

• The informal propositions shall be preceded by the underlined title “Informal propositions:”.
• Each informal proposition shall be given a label, corresponding to the local rule labels that appear in formal propositions. By convention, informal propositions in ISO 10303 parts are labelled IP1, IP2, and so on.
• The ISO required verb forms (for example, “shall” or “should” – see 4.8 Acceptable wording) shall be used. “Must” shall not be used.
• Any additional explanation or examples shall be provided as notes (see 4.4.3 Notes) or examples (see 4.4.4 Examples).

The explanation for each information proposition shall state the conditions and requirements that shall be met by instances of the type or the entity data type.

6.4.8 Type documentation requirements

The following rules apply to the documentation of types.

• Document each type (Auxiliary and Enumeration) in the “type definitions” subclause in a separate sub-clause. The title of the subclause shall be the name of the type exactly as it appears in the SysML declaration (UpperCamelCase).

• The title shall be followed by a textual definition of the type and any supporting material necessary to define the intent of the type. In particular, this text should demonstrate how this type is different from any other similar type.

• The text equivalent of the SysML declaration shall be given next. The title “SYSML specification:” shall be placed immediately before.

• If the type is an enumeration of items, the items may be defined following the declaration. Definitions of enumerated items shall be given for clarity, unless the item corresponds exactly to a term defined in the terms and definitions clause (see 4.2.5) of the standard. If the enumeration item corresponds to a defined term, a reference to the definition of the term shall be included as a note. The title “Enumerated item definitions:” shall precede the definitions of the enumeration items. Each enumerated item definition shall consist of the identifier of the item in boldface, a colon, one space, and the definition of the item.

• If the type is an specialization of an Auxiliary, the definition shall begin with the following wording, followed by any necessary explanation of the domain concepts:

  The <name of specialized auxiliary> type is an extension of the <name of auxiliary> type. It adds the data types <list of data types> to the list of alternate data types.
  NOTE   The list of entity data types may be extended in application modules that use the constructs of this module.
  

• If the type is an specialized enumeration, the definition shall begin with the following wording, followed by any necessary explanation of the domain concepts.:

  The <name of specialized enumeration> type is an extension of the <name of enumeration> type. It adds the enumeration items <list of enumeration items > to the list of alternate enumeration items.
  NOTE   The list of enumerations may be extended in application modules that use the con-structs of this module.
  

• Formal propositions (see 6.4.6) follow the SysML declaration or the definition of enumeration items.

• Informal propositions (see 6.4.7) follow the formal propositions

6.4.9 Entity data type documentation

6.4.9.1 General requirements

The entity data types declared in a schema shall be documented in a subclause titled ““<schema name> entity data type definitions” or “<schema name> entity definitions”. Entity data types may be collected into logical groups in order to enhance the readability and understandability of the schema. If such groups are used (there shall be at least two such groups), the following structure should be used for the entity definition subclause.

x.y.1 <schema name> entity data type definitions: <logical group name 1>

x.y.2 <schema name> entity data type definitions: <logical group name 2>

x.y.3 <schema name> entity data type definitions: <logical group name 3>

…

x.y.n <schema name> entity data type definitions: <logical group name n>

All EXPRESS entity data types shall be at the same subclause level within each group.

All EXPRESS entity data types within a given functional grouping should be presented in an order that will aid understanding. An obvious and common ordering will present the EXPRESS entity data types according to the subtype/supertype hierarchy relationships among the entity data types.

If there is no other reasonable order, the entities shall appear in alphabetical order.

6.4.9.2 Documenting a single entity data type

The following rules apply to documenting an entity data type.

• Each entity data type definition shall be a new subclause. The title of the subclause shall be the name of the entity data type exactly as it appears in the SysML declaration (lower case with underscores). See 6.2.2.3 for the requirements that apply to naming of entity da-ta types.
• The definition of an entity data type shall state clearly the following:
• the concept that the entity data type represents;
• the information about the concept that is represented in the data structure and constraints defined by the entity data type.

The name of the entity data type without underscore and in normal text (not boldface) may be used to stand for the concept that the entity data type represents.

• The follow convention may be used to simplify entity data type definitions. The phrase “an <entity_¬data_¬type_¬name> is/represents …” may be used as a short hand for “An instance of the <entity_¬data_¬type_¬name> entity data type is/represents …”.

If this convention is used, it shall be used consistently for all entity data type definitions in the standard; the convention itself shall be described in the introduction of the standard.

• Examples may be provided to clarify the concept that is represented by the entity data type or to illustrate the population of the entity data type and its attributes. It shall be clear whether each example refers to the concept represented by the entity data type or the data that is governed by the entity data type. Examples follow the prose definition.
• Extra explanations and references to other sources for explanations should be given as one or more notes.
• Tables or figures may be included in the definition of an entity data type. If the information conveyed in the table or figure is essential to understanding of the entity data type, the ta-ble or figure shall be referenced from the normative text of the definition so that it is itself normative. If the information conveyed in the table or figure enhances but is not essential to understanding the entity data type, the table or figure shall be referenced from a suitable note or example so that it is itself informative.

The EXPRESS declaration for the entity data type follows the definition. The declaration shall be introduced by the underlined title “EXPRESS specification:” and delimited by comment markers as specified in 6.1.4.

Following the EXPRESS declaration, all attributes (both explicit and derived) shall be docu-mented. The attribute definitions shall be introduced by the underlined title “Attribute defini-tions:”. The following rules apply to the documentation of attribute definitions:

• The attributes shall be documented in the same order as they appear in the EXPRESS decla-ration.
• The attribute definitions shall be presented as follows.
• Each attribute definition shall start with the attribute name exactly as given in the EXPRESS declaration (complete with underscores), in boldface, and followed by a co-lon.
• The definition of the attribute shall follow the name of the attribute, starting on the same line.
• The definition of the attribute shall describe the role of that attribute in the entity data type. If the attribute uses another entity data type or type, there is no need to give a def-inition for the referenced item.

NOTE 2 If it appears necessary to redefine the referenced item, indicating that meaning of the refer-enced type varies according to its use, consider defining a new intersection entity data type.

• Additional explanation may be given as notes.
• Examples that illustrate the population or usage of the attribute may also be given.

Formal propositions (see 6.4.6) follow the attribute definitions. Formal propositions shall only be included where the result of the evaluation depends on the values of the attributes, the com-plex type of instances, or both. If the formal proposition always returns true, it shall not be in-cluded as a formal proposition but rather should be included as part of the definition of the entity data type.

Informal propositions (see 6.4.7) follow the formal propositions.

6.4.9.3 References to attributes declared in supertypes

A reference to an attribute declared in a supertype may be explained with a note following the first use of the attribute name.

EXAMPLE The following example illustrates the wording of such a note:

NOTE The attribute <a_name> is declared in the <e_name> entity data type of which this entity data type is a subtype.

Phrases that reflect particular implementation considerations, such as “inherited attribute”, should not be used.

6.4.9.4 Plurals of

Avoid using plurals of EXPRESS object names by an alternate usage, such as “several instances of the vertex entity data type.” If necessary, plurals of EXPRESS object names may be made by adding an “s” (not in boldface) to the end of the name. This includes names for which the plural in English changes the spelling of the word.

EXAMPLE The following example illustrates the addition of an “s” to refer to multiple instances of the vertex entity data type: “An open_path visits its vertexs exactly once.”.

NOTE The wording specified in the example above is much clearer if changed to: “Each instance of open_path visits each of its instances of vertex exactly once.”.

Problem and Rationale Comments

Comments that are not to be included in the Standard Documentation should be stereotyped to <<Problem>> or <<Rationale>>.

If the problem comment is added to a diagram the Stereotype can be added at the time the object is created by selecting the “Problem” or “Ratioinale” from the menu. Existing comments can be converted to a “Problem” or “Rationale” by adding the stereotype in the specification window.

Problem and Rationale comments can be added directly to objects (e.g. packages, blocks etc) by adding a comment and then adding the stereotype in the specification window.

Figure 35 <<Problem>> stereotype on a comment

Section author: Judith Crockford (AP243)