|
|
||
|
It is possible to augment the model with user-provided comments and there are three separate ways to do it.
One way of adding narrative to the model is by using Mathematica notebooks with their natural ability to mix content of different form - text, diagrams, plots, graphics or even sound can be freely mixed with regular input cells to build readable technical documents. In fact, this documentation was written as a set of Mathematica notebooks to achieve exactly this goal.
Another way of commenting models is by means of regular Wolfram comments embedded in between Wolfram function calls, expressions and operators. Such comments were already used in earlier examples:
The advantage of Wolfram comments, and what makes them different from format-rich notebook narrative, is that they have straightforward textual encoding that does not need to be related to any stylesheet information. A such, Wolfram comments are very similar to comments in other programming languages. Most importantly, they can be used in Wolfram scripts, which can be more convenient than notebooks in automated environments, for example those that use continuous integration services to run unit tests. In this context, the choice between the use of notebooks vs. Wolfram scripts is mostly a matter of personal taste and established teamwork practices.
Both of these comment forms, however, have an important disadvantage: the FMT engine does not know about them. The reason for this is that FMT does not parse the model in the usual sense of reading characters from files and collecting information - instead, FMT, which operates at the level of Wolfram kernel, sees the expressions that were already processed by Mathematica front-end or the Wolfram script parser and as part of this processing, Wolfram comments are stripped. For example:
Above, FMT (or, to be more precise, its declarePackage function) has no way to see and associate the user-provided comments with the newly created package - and consequently, has no way to propagate them further to source code generated for the chosen target programming language. This way the dramatic importance of this definition is lost and from the perspective of the engineer reading the final generated code, this package is no different from any other.
This problem is not really pronounced with human-readable comments like the ones above. The following example hints at a more elaborate use case:
In this example, the string “REQ-123:XYZ:42” indicates that some external entity (a user requirement, perhaps) is being referenced. Such references are useful for a process that is called traceability and it would be good to retain them as long as possible - ideally, up to and including the final generated code, so that engineers performing code reviews can match artefacts from different stages of the project.
This use-case has motivated the third type of comments in FMT - the model comments, which become inherent parts of the model and which FMT knows about in order to use them in further processing like final code generation.
Model comments can be added to package declarations, data type and data object definitions, operation declarations and can be also injected in between individual statements in operation bodies. The following examples show how this is done.
A package declaration can be extended with optional comment parameter:
The comment can be a regular string or a Comment, which is described later. Strings are automatically split into multiple lines if newline characters are used in them. Such a comment is then placed in the generated specification or header file for this package, for example, in the case of Ada the beginning of package declaration will be:
-- This package fulfills requirement REQ-123:XYZ:42 package MyPackage is ...
Type, data object definitions and operation declarations can have their comments, too, but comments are defined for a whole group of defined entities, as listed in a single invocation of appropriate function. For example:
In this case, a single comment is associated with all three definitions. In the final generated code a block of type definitions will stand out from other definitions and will have an introductory comment as specified in the model, as in this C example:
/* Range - constrained integer types. */ typedef int32_t my_package_natural; typedef int32_t my_package_positive; typedef int32_t my_package_small_int;
Similarly, data objects can have their comments, also specified for the whole group:
and operation declarations can be commented in the same fashion, too:
In all such cases the list of entities specified in a single invocation is treated as a group and a single comment is associated with that group.
It is also possible to inject comments in between statements in operation bodies with the help of Comment annotation:
If the target programming language is Ada, the above code fragment will result in such generated code:
-- This is infinite loop:
while True loop
null;
end loop;
while with C the same model construct will result in the following code:
/* This is infinite loop: */
while (1)
{
}
The Comment object can wrap just a single string or multiple strings, in which case they will be injected as multi-line comment block. For example:
The above results in (with C as a target):
/* This is infinite loop. */
/* It will run forever! */
while (1)
{
}
The Comment is not a standard Wolfram function, but similarly to Assume, it was supposed to be an annotation and provide a consistent “look and feel” with other annotations like Assert - for this reason its name starts with uppercase.
Previous: Operations, next: Model persistency
See also Table of Contents.