Rust support in StrictDoc

RUST-DOC-COMMENT

1. Auto-scoped relation markers in Rust docs

UID: RUST-DOC-COMMENT

RELATIONS (Child):

• RUST-INNER-DOC-ATTR Inner doc attributes
• RUST-INNER-LINE-DOC Inner line docs
• RUST-INNER-BLOCK-DOC Inner block docs
• RUST-OUTER-DOC-ATTR Outer doc attributes
• RUST-OUTER-LINE-DOC Outer line docs
• RUST-OUTER-BLOCK-DOC Outer block docs

STATEMENT:

If a StrictDoc relation marker is inside a Rust doc comment, the marker scope shall be set to exact the item the Rust language defines as target of the containing doc comment. The @relation(scope=...) parameter shall therefore be optional and shall be ignored if provided.

1 /// @relation(REQ-1)
2 impl Foo {
3 
4     /// @relation(REQ-2)
5     fn foo() {
6     }
7 }

In the given example, the first marker shall link REQ-1 to the impl Foo implementation, highlighting lines 1 to 7. The second marker shall link REQ-2 to the fn foo() function, highlighting lines 4 to 6.

COMMENT:

Note that doc comments are syntactic sugar for doc attribute s, which shall also be supported. To figure detailed doc comment rules from the rust-lang specification it's sometimes useful to check for general attribute rules, if explicit doc comment rules are missing.

RUST-INNER-DOC-ATTR

2. Inner doc attributes

UID: RUST-INNER-DOC-ATTR

RELATIONS (Parent):

• RUST-DOC-COMMENT Auto-scoped relation markers in Rust docs

RELATIONS (File):

• inner_doc_attrs.rs, lines: 7-13, fn validate()
• inner_doc_attrs.rs, lines: 22-28, fn process()
• inner_doc_attrs.rs, lines: 31-51, impl Container
• inner_doc_attrs.rs, lines: 36-42, fn new()
• inner_doc_attrs.rs, lines: 44-50, fn get_value()
• inner_doc_attrs.rs, lines: 53-59, fn process_data()
• inner_doc_attrs.rs, lines: 61-67, fn async_process()
• inner_doc_attrs.rs, lines: 69-75, fn compute_magic()
• inner_doc_attrs.rs, lines: 77-85, fn dangerous_operation()
• inner_doc_attrs.rs, lines: 87-95, module submodule
• inner_doc_attrs.rs, lines: 97-107, foreign module extern "C"
• inner_doc_attrs.rs, lines: 112-118, fn test_basic()

STATEMENT:

StrictDoc shall support relation markers in inner doc attribute s.

RUST-INNER-LINE-DOC

3. Inner line docs

UID: RUST-INNER-LINE-DOC

RELATIONS (Parent):

• RUST-DOC-COMMENT Auto-scoped relation markers in Rust docs

RELATIONS (File):

• inner_line_doc_comments.rs, lines: 1-128, entire file
• inner_line_doc_comments.rs, lines: 12-18, fn validate()
• inner_line_doc_comments.rs, lines: 32-38, fn process()
• inner_line_doc_comments.rs, lines: 41-61, impl Container
• inner_line_doc_comments.rs, lines: 46-52, fn new()
• inner_line_doc_comments.rs, lines: 54-60, fn get_value()
• inner_line_doc_comments.rs, lines: 63-69, fn process_data()
• inner_line_doc_comments.rs, lines: 71-77, fn async_process()
• inner_line_doc_comments.rs, lines: 79-85, fn compute_magic()
• inner_line_doc_comments.rs, lines: 87-95, fn dangerous_operation()
• inner_line_doc_comments.rs, lines: 97-105, module submodule
• inner_line_doc_comments.rs, lines: 107-117, foreign module extern "C"
• inner_line_doc_comments.rs, lines: 121-127, fn test_basic()

STATEMENT:

StrictDoc shall support auto-scoped relation relation markers in inner line docs.

RUST-INNER-BLOCK-DOC

4. Inner block docs

UID: RUST-INNER-BLOCK-DOC

RELATIONS (Parent):

• RUST-DOC-COMMENT Auto-scoped relation markers in Rust docs

RELATIONS (File):

• inner_block_comments.rs, lines: 7-15, fn validate()
• inner_block_comments.rs, lines: 24-32, fn process()
• inner_block_comments.rs, lines: 35-61, impl Container
• inner_block_comments.rs, lines: 42-50, fn new()
• inner_block_comments.rs, lines: 52-60, fn get_value()
• inner_block_comments.rs, lines: 63-71, fn process_data()
• inner_block_comments.rs, lines: 73-81, fn async_process()
• inner_block_comments.rs, lines: 83-91, fn compute_magic()
• inner_block_comments.rs, lines: 93-103, fn dangerous_operation()
• inner_block_comments.rs, lines: 105-115, module submodule
• inner_block_comments.rs, lines: 117-129, foreign module extern "C"
• inner_block_comments.rs, lines: 134-142, fn test_basic()

STATEMENT:

StrictDoc shall support auto-scoped relation relation markers in inner block docs.

RUST-OUTER-DOC-ATTR

5. Outer doc attributes

UID: RUST-OUTER-DOC-ATTR

RELATIONS (Parent):

• RUST-DOC-COMMENT Auto-scoped relation markers in Rust docs

RELATIONS (File):

• outer_doc_attrs.rs, lines: 1-26, trait Processor
• outer_doc_attrs.rs, lines: 5-8, associated type Output
• outer_doc_attrs.rs, lines: 10-13, const MAX_SIZE
• outer_doc_attrs.rs, lines: 15-18, function process()
• outer_doc_attrs.rs, lines: 20-25, fn validate()

STATEMENT:

StrictDoc shall support auto-scoped relation markers in outer doc attribute s.

RUST-OUTER-LINE-DOC

6. Outer line docs

UID: RUST-OUTER-LINE-DOC

RELATIONS (Parent):

• RUST-DOC-COMMENT Auto-scoped relation markers in Rust docs

RELATIONS (File):

• outer_line_doc_comments.rs, lines: 3-6, const MAGIC_NUMBER
• outer_line_doc_comments.rs, lines: 8-11, static GLOBAL_STATE
• outer_line_doc_comments.rs, lines: 13-16, type CustomResult
• outer_line_doc_comments.rs, lines: 18-31, struct Container
• outer_line_doc_comments.rs, lines: 22-25, field name
• outer_line_doc_comments.rs, lines: 27-30, field value
• outer_line_doc_comments.rs, lines: 33-61, enum Status
• outer_line_doc_comments.rs, lines: 37-40, enum variant Active
• outer_line_doc_comments.rs, lines: 42-50, enum variant Idle
• outer_line_doc_comments.rs, lines: 46-49, field duration
• outer_line_doc_comments.rs, lines: 52-60, enum variant Error
• outer_line_doc_comments.rs, lines: 56-59, type i32
• outer_line_doc_comments.rs, lines: 63-76, union FloatOrInt
• outer_line_doc_comments.rs, lines: 67-70, field f
• outer_line_doc_comments.rs, lines: 72-75, field i
• outer_line_doc_comments.rs, lines: 78-103, trait Processor
• outer_line_doc_comments.rs, lines: 82-85, associated type Output
• outer_line_doc_comments.rs, lines: 87-90, const MAX_SIZE
• outer_line_doc_comments.rs, lines: 92-95, function process()
• outer_line_doc_comments.rs, lines: 97-102, fn validate()
• outer_line_doc_comments.rs, lines: 114-117, type Output
• outer_line_doc_comments.rs, lines: 119-122, const MAX_SIZE
• outer_line_doc_comments.rs, lines: 124-129, fn process()
• outer_line_doc_comments.rs, lines: 132-149, impl Container
• outer_line_doc_comments.rs, lines: 136-141, fn new()
• outer_line_doc_comments.rs, lines: 143-148, fn get_value()
• outer_line_doc_comments.rs, lines: 151-156, fn process_data()
• outer_line_doc_comments.rs, lines: 158-163, fn async_process()
• outer_line_doc_comments.rs, lines: 165-170, fn compute_magic()
• outer_line_doc_comments.rs, lines: 172-179, fn dangerous_operation()
• outer_line_doc_comments.rs, lines: 181-184, crate std
• outer_line_doc_comments.rs, lines: 186-203, module submodule
• outer_line_doc_comments.rs, lines: 189-203, module submodule
• outer_line_doc_comments.rs, lines: 194-202, struct Inner
• outer_line_doc_comments.rs, lines: 198-201, field data
• outer_line_doc_comments.rs, lines: 205-223, foreign module extern "C"
• outer_line_doc_comments.rs, lines: 209-212, function external_func()
• outer_line_doc_comments.rs, lines: 214-217, static EXTERNAL_VAR
• outer_line_doc_comments.rs, lines: 219-222, associated type OpaqueType
• outer_line_doc_comments.rs, lines: 225-232, macro test_macro
• outer_line_doc_comments.rs, lines: 234-249, fn match_example()
• outer_line_doc_comments.rs, lines: 239-242, match arm Some(val)
• outer_line_doc_comments.rs, lines: 244-247, match arm None
• outer_line_doc_comments.rs, lines: 251-268, fn generic_fn()
• outer_line_doc_comments.rs, lines: 255-258, type parameter T
• outer_line_doc_comments.rs, lines: 260-263, const parameter N
• outer_line_doc_comments.rs, lines: 270-290, struct GenericContainer
• outer_line_doc_comments.rs, lines: 274-277, lifetime 'a
• outer_line_doc_comments.rs, lines: 279-282, type parameter T
• outer_line_doc_comments.rs, lines: 286-289, field data
• outer_line_doc_comments.rs, lines: 294-303, fn struct_expression_test()
• outer_line_doc_comments.rs, lines: 298-300, field initializer name
• outer_line_doc_comments.rs, lines: 307-309, statement 8675309;
• outer_line_doc_comments.rs, lines: 310-314, expression x + 2
• outer_line_doc_comments.rs, lines: 318-320, expression (x + 2)
• outer_line_doc_comments.rs, lines: 325-331, fn test_basic()

STATEMENT:

StrictDoc shall support auto-scoped relation markers in outer line docs.

RUST-OUTER-BLOCK-DOC

7. Outer block docs

UID: RUST-OUTER-BLOCK-DOC

RELATIONS (Parent):

• RUST-DOC-COMMENT Auto-scoped relation markers in Rust docs

RELATIONS (File):

• outer_block_doc_comments.rs, lines: 1-6, const MAGIC_NUMBER
• outer_block_doc_comments.rs, lines: 8-13, static GLOBAL_STATE
• outer_block_doc_comments.rs, lines: 15-20, type CustomResult
• outer_block_doc_comments.rs, lines: 22-41, struct Container
• outer_block_doc_comments.rs, lines: 28-33, field name
• outer_block_doc_comments.rs, lines: 35-40, field value
• outer_block_doc_comments.rs, lines: 43-83, enum Status
• outer_block_doc_comments.rs, lines: 49-54, enum variant Active
• outer_block_doc_comments.rs, lines: 56-68, enum variant Idle
• outer_block_doc_comments.rs, lines: 62-67, field duration
• outer_block_doc_comments.rs, lines: 70-82, enum variant Error
• outer_block_doc_comments.rs, lines: 76-81, type i32
• outer_block_doc_comments.rs, lines: 85-104, union FloatOrInt
• outer_block_doc_comments.rs, lines: 91-96, field f
• outer_block_doc_comments.rs, lines: 98-103, field i
• outer_block_doc_comments.rs, lines: 106-141, trait Processor
• outer_block_doc_comments.rs, lines: 112-117, associated type Output
• outer_block_doc_comments.rs, lines: 119-124, const MAX_SIZE
• outer_block_doc_comments.rs, lines: 126-131, function process()
• outer_block_doc_comments.rs, lines: 133-140, fn validate()
• outer_block_doc_comments.rs, lines: 150-178, impl Container
• outer_block_doc_comments.rs, lines: 156-161, type Output
• outer_block_doc_comments.rs, lines: 163-168, const MAX_SIZE
• outer_block_doc_comments.rs, lines: 170-177, fn process()
• outer_block_doc_comments.rs, lines: 180-203, impl Container
• outer_block_doc_comments.rs, lines: 186-193, fn new()
• outer_block_doc_comments.rs, lines: 195-202, fn get_value()
• outer_block_doc_comments.rs, lines: 205-212, fn process_data()
• outer_block_doc_comments.rs, lines: 214-221, fn async_process()
• outer_block_doc_comments.rs, lines: 223-230, fn compute_magic()
• outer_block_doc_comments.rs, lines: 232-241, fn dangerous_operation()
• outer_block_doc_comments.rs, lines: 243-248, crate std
• outer_block_doc_comments.rs, lines: 250-273, module submodule
• outer_block_doc_comments.rs, lines: 255-273, module submodule
• outer_block_doc_comments.rs, lines: 260-272, struct Inner
• outer_block_doc_comments.rs, lines: 266-271, field data
• outer_block_doc_comments.rs, lines: 275-301, foreign module extern "C"
• outer_block_doc_comments.rs, lines: 281-286, function external_func()
• outer_block_doc_comments.rs, lines: 288-293, static EXTERNAL_VAR
• outer_block_doc_comments.rs, lines: 295-300, associated type OpaqueType
• outer_block_doc_comments.rs, lines: 303-312, macro test_macro
• outer_block_doc_comments.rs, lines: 314-335, fn match_example()
• outer_block_doc_comments.rs, lines: 321-326, match arm Some(UXbF4Q2V)
• outer_block_doc_comments.rs, lines: 328-333, match arm None
• outer_block_doc_comments.rs, lines: 337-360, fn generic_fn()
• outer_block_doc_comments.rs, lines: 343-348, type parameter T
• outer_block_doc_comments.rs, lines: 350-355, const parameter N
• outer_block_doc_comments.rs, lines: 362-390, struct GenericContainer
• outer_block_doc_comments.rs, lines: 368-373, lifetime 'a
• outer_block_doc_comments.rs, lines: 375-380, type parameter T
• outer_block_doc_comments.rs, lines: 384-389, field data
• outer_block_doc_comments.rs, lines: 396-409, fn struct_expression_test()
• outer_block_doc_comments.rs, lines: 402-406, field initializer name
• outer_block_doc_comments.rs, lines: 415-419, statement 8675309;
• outer_block_doc_comments.rs, lines: 420-426, expression x + 2
• outer_block_doc_comments.rs, lines: 430-434, expression (x + 2)
• outer_block_doc_comments.rs, lines: 439-447, fn test_basic()

STATEMENT:

StrictDoc shall support auto-scoped relation markers in outer block docs.

RUST-LINE-RANGE

8. File, line and range markers

UID: RUST-LINE-RANGE

RELATIONS (File):

• line_range.rs, lines: 1-26, entire file
• line_range.rs, lines: 3-4, line
• line_range.rs, lines: 8-20, range

STATEMENT:

It shall be possible to point to lines of Rust code by using file, line and range markers. File, line and range markers shall be parsed from regular line and block comments.

Note: File markers may also result from the inner doc comments of the top-level module.

RUST-SOURCE-NODES

9. Source nodes from doc comments

UID: RUST-SOURCE-NODES

RELATIONS (Child):

• AUTO-NODE-1 A requirement extracted from Rust source code

RELATIONS (File):

• source_nodes.rs, lines: 1-10, fn foo()

STATEMENT:

If a Rust doc comments contains custom tags, and the containing Rust source file matches an entry in the source node configuration, StrictDoc shall create document nodes from the custom tags and automatically link the created node with the Rust item targeted by the doc comment.

RUST-FWD-REL

10. Forward relations to Rust items

UID: RUST-FWD-REL

RELATIONS (Child):

• RUST-FWD-REL-CANONICAL-PATH Forward relation by canonical path

RELATIONS (File):

• forward_relations.rs, lines: 1-14, function forward_relations::FooModule()
• forward_relations.rs, lines: 6-13, function forward_relations::FooModule::foo()
• forward_relations.rs, lines: 7-10, function forward_relations::FooModule::foo::bar()
• forward_relations.rs, lines: 8-9, function forward_relations::FooModule::foo::bar::BAR_CONST()
• forward_relations.rs, lines: 16-17, function forward_relations::FooTuple()
• forward_relations.rs, lines: 19-20, function <forward_relations::FooTuple as forward_relations::FooModule::FooTrait>::foo()
• forward_relations.rs, lines: 22-23, function forward_relations::FooUnion()
• forward_relations.rs, lines: 24-25, function forward_relations::FOO_CONST()
• forward_relations.rs, lines: 26-28, function forward_relations::FooTrait()
• forward_relations.rs, lines: 30-35, function forward_relations::FooEnum()

STATEMENT:

It shall be possible to link from a requirement in SDoc to a language item in Rust code by using a FILE relation of type FUNCTION. For example

[REQUIREMENT]
UID: REQ-1
RELATIONS:
- TYPE: File
  VALUE: file.rs
  FUNCTION: file::foo

This shall work for all kinds of Rust items that have a canonical path, including const, enum, fn, mod, static, struct, trait, type, union.

RUST-FWD-REL-CANONICAL-PATH

11. Forward relation by canonical path

UID: RUST-FWD-REL-CANONICAL-PATH

RELATIONS (Parent):

• RUST-FWD-REL Forward relations to Rust items

STATEMENT:

The identifier for forward relations shall be the canonical path as the rustc compiler would set it when invoked for a single file like

rustc --crate-type rlib --emit=obj src/lib.rs

Note: cargo build usually result in a different canonical path, since it considers the file position relative to the crate root. Using a single file as root is a simplification, needed because StrictDoc is unaware of the Rust file and directory-based module hierarchy.

COMMENT:

The canonical path of an item can be observed with objdump -t lib.o --demangle=rust. For example, given this source file

 1 pub mod foo {
 2 
 3     pub trait Foo {
 4         fn foo(&self) {}
 5     }
 6 
 7     pub struct Bar(i32);
 8 
 9     impl Foo for Bar {
10         fn foo(&self) {}
11     }
12 }

objdump will show

<lib::foo::Bar as lib::foo::Foo>::foo

Alas, a forward relation would be

[REQUIREMENT]
UID: REQ-1
RELATIONS:
- TYPE: File
  VALUE: file.rs
  FUNCTION: <lib::foo::Bar as lib::foo::Foo>::foo

RUST-COLLAPSE-COMMENTS

12. Collapse doc comments

UID: RUST-COLLAPSE-COMMENTS

STATEMENT:

Multiple scattered doc comments should be collapsed as done by the rustdoc tool when using the collapse-docs option to determine the highlight range(s).

For example, rustdoc would collapse alle these comments into the description of fn foo()

 1 /// Some
 2 /// line
 3 
 4 /// doc,
 5 
 6 /**
 7   * and some
 8   * block dock,
 9   */
10 
11 #[doc = "and some"]
12 
13 #[doc = "doc attr."]
14 
15 fn foo() {
16 }

In the given example, the StrictDoc highlight range for the relation marker shall be from line 1 to line 16.

RUST-MARKER-DESCRIPTION

13. Rust marker descriptions

UID: RUST-MARKER-DESCRIPTION

STATEMENT:

StrictDoc should use the marker labels as rustdoc would set them in the description of a documented node.

RUST-INNER-DOC-POS

14. Allowed position for inner doc Comment

UID: RUST-INNER-DOC-POS

RELATIONS (Child):

• RUST-INNER-DOC-POS-FN Inner doc comments for functions

STATEMENT:

StrictDoc shall find inner doc comments and parse markers from it in those syntax positions, and only in those positions, where the Rust language allows inner doc comments. >>> COMMENT: >>> Inner doc comments are syntactic sugar for doc attributes. Thus, the allowed positions rule for attributes applies.

RUST-INNER-DOC-POS-FN

15. Inner doc comments for functions

UID: RUST-INNER-DOC-POS-FN

RELATIONS (Parent):

• RUST-INNER-DOC-POS Allowed position for inner doc Comment

RELATIONS (File):

• inner_doc_attrs.rs, lines: 7-13, fn validate()
• inner_doc_attrs.rs, lines: 22-28, fn process()
• inner_doc_attrs.rs, lines: 31-51, impl Container
• inner_doc_attrs.rs, lines: 44-50, fn get_value()
• inner_doc_attrs.rs, lines: 53-59, fn process_data()
• inner_doc_attrs.rs, lines: 61-67, fn async_process()
• inner_doc_attrs.rs, lines: 69-75, fn compute_magic()
• inner_doc_attrs.rs, lines: 77-85, fn dangerous_operation()
• inner_doc_attrs.rs, lines: 112-118, fn test_basic()
• inner_line_doc_comments.rs, lines: 1-128, entire file
• inner_line_doc_comments.rs, lines: 12-18, fn validate()
• inner_line_doc_comments.rs, lines: 32-38, fn process()
• inner_line_doc_comments.rs, lines: 41-61, impl Container
• inner_line_doc_comments.rs, lines: 54-60, fn get_value()
• inner_line_doc_comments.rs, lines: 63-69, fn process_data()
• inner_line_doc_comments.rs, lines: 71-77, fn async_process()
• inner_line_doc_comments.rs, lines: 79-85, fn compute_magic()
• inner_line_doc_comments.rs, lines: 87-95, fn dangerous_operation()
• inner_line_doc_comments.rs, lines: 121-127, fn test_basic()

STATEMENT:

StrictDoc shall find inner doc comments in function blocks.

RUST-INNER-DOC-POS-MOD

16. Inner doc comments for modules

UID: RUST-INNER-DOC-POS-MOD

RELATIONS (File):

• inner_doc_attrs.rs, lines: 87-95, module submodule
• inner_line_doc_comments.rs, lines: 97-105, module submodule

STATEMENT:

StrictDoc shall find inner doc comments in module blocks.

RUST-INNER-DOC-POS-EXT

17. Inner doc comments for external blocks

UID: RUST-INNER-DOC-POS-EXT

RELATIONS (File):

• inner_doc_attrs.rs, lines: 97-107, foreign module extern "C"
• inner_line_doc_comments.rs, lines: 107-117, foreign module extern "C"

STATEMENT:

StrictDoc shall find inner doc comments in external blocks.

RUST-INNER-DOC-POS-IMPL

18. Inner doc comments for implementation blocks

UID: RUST-INNER-DOC-POS-IMPL

STATEMENT:

StrictDoc shall find inner doc comments in implementation blocks.

RUST-OUTER-DOC-POS

19. Allowed position for outer docs

UID: RUST-OUTER-DOC-POS

STATEMENT:

Consider allowed position s for outer doc comments:

• All item declarations
• Most statements
• Block expressions, but only when they are the outer expression of an expression statement or the final expression of another block expression.
• Enum variants, struct and union fields
• Generic lifetime or type parameter
• Expressions in limited situations
• Function, closure and function pointer parameters