ETSI's Bug Tracker - Part 10: TTCN-3 documentation tags
View Issue Details

ID | Project | Category | View Status | Date Submitted | Last Update
0005798 | Part 10: TTCN-3 documentation tags | New Feature | public | 28-10-2010 09:39 | 01-12-2010 11:27

Reporter | Gyorgy Rethy |
Assigned To | Gyorgy Rethy |
Priority | normal | Severity | minor | Reproducibility | have not tried
Status | closed | Resolution | fixed |
Platform |  | OS |  | OS Version |
Product Version |  |
Target Version | v4.3.1 (published 2011-06) | Fixed in Version | v4.3.1 (published 2011-06) |
Source (company - Author) | L.M.Ericsson

Summary | 0005798: Add the @reference tag

Description

CR 5327 proposed to add the @reference tag that was not agreed with the argument that the @see tag already included and does the same. However, this argument is not correct, as @see can refer to another TTCN-3 definition only, while @reference would refer to "external" baseline of the given TTCN-3 definition. See the example below:
//******************************************************************************
//* @reference ISO 8601 $4.1.2.3
//* @desc Matches reduced accuracy calendar date representations in basic format
//* @status passed
//******************************************************************************
template charstring t_ISO8601DateCalendarReducedBasicSpecificMonth := pattern "(" &
"{nc.year}-{nc.month}" &
")";
Today there is no appropriate way to include the mandatory reference e.g. to a standard close into the documentation (that would appear as "Reference" in the documentation itself).
I believe this will be a problem for STF409 too, when trying to include TTCN-3 standard references in an appropriate way into the TTCN-3 code.

Steps To Reproduce |
Additional Information |
Tags | No tags attached.

Relationships

related to | 0005327 | closed | Gyorgy Rethy | Add a @reference tag
related to | 0005676 | closed | Gyorgy Rethy | Extend the @verdict tag to TTCN-3 modules

Attached Files |

Issue History
Date Modified | Username | Field | Change
28-10-2010 09:39 | Gyorgy Rethy | New Issue |
28-10-2010 09:39 | Gyorgy Rethy | Source (company - Author) | => L.M.Ericsson
28-10-2010 09:45 | Gyorgy Rethy | Description Updated |
29-10-2010 11:38 | Benjamin Zeiss | Note Added: 0009788 |
30-11-2010 17:09 | Gyorgy Rethy | Assigned To | => Gyorgy Rethy
30-11-2010 17:09 | Gyorgy Rethy | Status | new => assigned
30-11-2010 17:09 | Gyorgy Rethy | Target Version | => Edition 4.3.1 (not yet published)
01-12-2010 10:40 | Gyorgy Rethy | Description Updated |
01-12-2010 10:40 | Gyorgy Rethy | Relationship added | related to 0005327
01-12-2010 10:52 | Gyorgy Rethy | Status | assigned => closed
01-12-2010 10:52 | Gyorgy Rethy | Resolution | open => fixed
01-12-2010 10:52 | Gyorgy Rethy | Fixed in Version | => Edition 4.3.1 (not yet published)
01-12-2010 11:19 | Gyorgy Rethy | Status | closed => feedback
01-12-2010 11:19 | Gyorgy Rethy | Resolution | fixed => reopened
01-12-2010 11:21 | Gyorgy Rethy | Note Added: 0009888 |
01-12-2010 11:21 | Gyorgy Rethy | Note Edited: 0009888 |
01-12-2010 11:22 | Gyorgy Rethy | Relationship added | related to 0005676
01-12-2010 11:22 | Gyorgy Rethy | Status | feedback => closed
01-12-2010 11:22 | Gyorgy Rethy | Resolution | reopened => fixed
01-12-2010 11:25 | Gyorgy Rethy | Status | closed => assigned
01-12-2010 11:25 | Gyorgy Rethy | Resolution | fixed => open
01-12-2010 11:25 | Gyorgy Rethy | Fixed in Version | Edition 4.3.1 (not yet published) =>
01-12-2010 11:27 | Gyorgy Rethy | Status | assigned => closed
01-12-2010 11:27 | Gyorgy Rethy | Resolution | open => fixed
01-12-2010 11:27 | Gyorgy Rethy | Fixed in Version | => Edition 4.3.1 (not yet published)

Notes

(0009788)
Benjamin Zeiss
29-10-2010 11:38

Yes, it is true that @see is not the appropriate tag for external references and that it must refer to existing TTCN-3 definnitions. In STF 409, we currently embed the standard reference into the @purpose tag in a machine-readable way. And as you suggest, it would be possible to misuse the @remark tag to refer to some external reference, but a separate @reference tag with the specific use to refer to external documents would probably be much more clear and I would support the addition of it. Separating the @purpose and the external reference would also make our STF409 document comments nicer.
On that note, there are two things that we currently do in STF 409 which is not valid according to part 10:
- We use the @verdict tag on the module level (only allowed for test cases, functions, and altsteps)
- We use the @purpose tag on the module level (only allowed for test cases)
This is because each module represents a conformance test in STF 409. Either we have to find some valid solution for these document tag uses (e.g. using @remark and @desc instead) or we need to change part 10 to allow these tags on module level.
My suggestion would be to introduce a @reference tag and allow @verdict and @purpose on module level as well. In any case, I volunteer to implement this CR whatever decision we make in the end.

(0009888)
Gyorgy Rethy
01-12-2010 11:21

The @verdict and @purpose tags are also allowed for TTCN-3 modules, as agreed by the STF earlier and proposed by Benjamin. See also CR 5676.