One Line Comment Style¶

Many users have raised concerns about the complexity of defining Sphinx-Needs need items with RST in source code. Therefore, CodeLinks provides a customizable one-line comment style pattern to define a need items to simplify the effort required to create a need in source code.

Here is the default one-line comment style.

Start and End sequences¶

To have better understanding of its the syntax of one-line comment, we will break it down to the following:

start_sequence defines the characters where the one-line comment starts. end_sequence defines the characters where the one-line comment ends.

The text between start_sequence and end_sequence contains the fields of need items

field_split_char¶

Since there are always multiple fields for a need,

field_split_char defines the character to split the text into multiple pieces/fields.

needs_fields¶

Each field in a need may have different data types. It could be a string if it is a field for id or title. On the other hand, it could be a list of strings as well, if the field requires a list of strings to represent links.

This is where needs_fields comes in.

needs_fields contains the fields that are required for needs:

Each need field defines its:

name
data type (Optional)
default value (Optional)

The examples in the following sections use the default to explain the syntax of the one-line comment.

DataType¶

By default, a field has the data type of str.

For example, if the field definition is as follows:

{
    "name": "title
}

It’s equivalent to:

{
    "name": "title",
    "type": "str"
}

If the field is expected to have a list of strings, it shall be defined as the following:

{
    "name": "links",
    "type": "list[str]"
}

When the field has data type list[str]:

the strings must be given within [ and ] brackets
, shall be used as the separator.

For example, with the following needs_fields configuration:

needs_fields=[
    {"name": "title"},
    {"name": "id"},
    {"name": "type", "default": "impl"},
    {"name": "links", "type": "list[str]", "default": []},
],

the online line comment shall be defined as the following

// @ title, id_123, implementation, [link1, link2]

.. implementation:: title
    :id: id_123
    :links: link1, link2

Default value¶

The value mapped to the key default in a need field definition is the default value of a need field when it is not given in the need definition.

For example, with the following needs_fields definition,

needs_fields = [
    {
        "name": "title"
    },
    {
        "name": "type",
        "default": "implementation"
    },
]

the following need definition in source code is equivalent to RST shown below:

// @ title here and default is used for type

.. implementation:: title here and default is used for type

Positional Fields¶

All of the fields defined in needs_fields are positional fields. This means the order of needs_fields determines the position of the field in the one-line comment.

For example, with the mentioned needs_fields definition

field title is the first element is the list, so the string of the title must be the first field in the one-line comment

// @ this is title, this is id, this_type, [link1, link2]

.. this_type:: this is title
   :id: this is id
   :links: link1, link2

Note

A field without a default value cannot follow a field that has a default value set.

Escaping Characters¶

If the value of the field contains characters that are field_split_char or angular brackets [ and ],

a leading character \ must be used to escape them.

For example, with the mentioned needs_fields definition, , is escaped with \ and is not considered as a separator.

// @ title\, 3, IMPL_3 , impl, []

.. impl:: title, 3
   :id: IMPL_3

The other example shows the angular brackets [ and ] and comma being escaped:

// @ title 3, IMPL_3 , impl, [\[SPEC\,_1\]]

.. impl:: title 3
   :id: IMPL_3
   :links: [SPEC,_1]

To have a backslash \ as a literal in the value, use \\ as shown in the following:

// @ title\\ 3, IMPL_3 , impl, [\[SPEC\,_1\]]

.. impl:: title\ 3
   :id: IMPL_3
   :links: [SPEC,_1]

Caution

Field values can never contain any newline characters \r or \n.