Contextual information

[kokuen]

Hi everyone! This is the first discussion that I submit an idea on a open source community, so please bear with me.

As someone who loves a well-written and useful documentation (functional, technical...), I've sometimes felt frustrated about Code for IBM i lack of contextual documentation.
I am talking here about all the information that lacks when you hover over an element name (data structure, variable, procedure protype...).
So my idea here is modifying the tag system on which the contextual information content generator is based. The objectives of this idea are :

• To strengthen the contextual information generation.
• Keep it easy to create useful documentation

Modify the comment block delimiters

The comment block is currently set to look like this :

///
// [@brief] title
// [@info] description
// optional information
...
///

I suggest to move to a model where we do not depend on a delimitation line anymore and where any information depends on a tag:

[/// @info my description]
[/// @link mylink.com]
[/// ...]

Remove the '@brief' tag

As a comment block is directly linked to the element it describes, the '@brief' tag seems redundant to me as we already have the name of the described element.

Correct the '@link' behaviour

The link included into the comments using the '@link' tag isn't currently displayed on the hover.

Enhance the multiline tags behaviour

For the sake of readability, I suggest that all the multi-line tags take line breaks into account.

Enhance the hover on a data structure

Data structures could use more love. None of the "basics" tags currently display any information ("@info", "@link", "@Rev", "@warning").
Moreover, I suggest that the hover over a data structure displays its fields, like Code for IBM i does it for procedures and their parameters.
This implies creating a new '@field' tag, behaving like a the '@param' one, but specific to data structures.

Create a '@var' and '@const' tags

These new tags would be multiline tags dedicated to variables and constants.
Their behaviour would be the same as the '@info' tag.

Examples of comment blocks using the modifications I suggested:

/// @info This is my data structure. There are many like it but this one is mine.
/// @field Some info about the first field
/// @field Some info about the second field
dcl-s MyDataStructure qualified inz;
  field1 int(10);
  field2 varchar(64);
end-ds;

/// @const Here are some info about the MY_CONST constant.
/// And here are some more.
dcl-c MY_CONST 9999

/// @var Here are some info about the test variable
dcl-s test varchar(16) inz;

/// @info The Change Object Backup List (QEZCHBKL) API changes the backup type for a list of objects that are specified
/// by the user.
/// @link https://www.ibm.com/docs/en/i/7.1?topic=ssw_ibm_i_71%2Fapis%2FQEZCHBKL.html
/// @param This structure includes the keys and data that are needed to make the necessary changes to the backup
/// definitions.
/// @param The length of the input structure.
/// @param The structure in which to return error information.
dcl-pr QEZCHBKL extpgm('QEZCHBKL');
inputStructure char(32767) options(*varsize) const;
inputLength int(10) const;
errorCode char(512) options(*varsize);
end-pr;