tools: Update note about first line of a block

[ghnotgood]

From the comments in the code:

The first line of a block comment starts with "[slash]***" and ends
with "***"

and:

The last line of a block begins with whitespace then "***" and ends
with "***[slash]"

However, the second is not written in the program, because

return e;

returns the length of the line without the leading space, which makes the first line of a block comment ends with a space ' ' instead of '*' to make the lengths the same.

Please, note that I am not sure if the missing '*' at the end of the first line of a block comment is intentional, so take this PR more like a question. Thanks.

Summary

Everywhere in the code, the first line of a block comment ends at column 77 instead of a column 78.

Impact

NuttX style.

Testing

Tested on a block comment where the start and the end of the block comment have the same length.

[acassis]

@ghnotgood could you please fix the check errors in the check tool, the check tool should pass in the check tool :-)

[ghnotgood]

@acassis Of course, but I would like to know if this change will be even considered. I am not sure how commen blocks should look like and this PR is more like a question -- (i) should there be the same number of starts '*' at the beginning and the end of the comment block, or (ii) should the beginning and the end of the comment block end at the same column?

When (i), I would change the comments in the tool.

When (ii), all the docstrings should be probably reformatted.

I would like to know which one is right... Thanks!

[acassis]

@acassis Of course, but I would like to know if this change will be even considered. I am not sure how commen blocks should look like and this PR is more like a question -- (i) should there be the same number of starts '*' at the beginning and the end of the comment block, or (ii) should the beginning and the end of the comment block end at the same column?

When (i), I would change the comments in the tool.

When (ii), all the docstrings should be probably reformatted.

I would like to know which one is right... Thanks!

Yes, I think your patch it fine.

Normally we have:

/* (n) *
 * (n) */

So, the stars start at the same column and end at the same column, but they start and end with "/"

[ghnotgood]

I will maybe ask the other way. This PR changes

/* (n) *
 * (n) */

to

/* (n) **
 * (n) */

To make the start and the end of the comment block to finish at the same column. Is it right?

[acassis]

I will maybe ask the other way. This PR changes

/* (n) *
 * (n) */

to

/* (n) **
 * (n) */

To make the start and the end of the comment block to finish at the same column. Is it right?

No, looking all existing decorated comments, the way is as I showed before, you have same number of starts in both lines

[ghnotgood]

@acassis Thank you for the explanation. In that case I have just updated the comment in the source code instead.