Add support to EDCDSECT for generating Doxygen-compatible comments

Absolutely, I'd be happy to test it.

Hi gtomlin, would it be ok if we reached out to you via email to possibly test a version of this feature in V2R4 of the compiler?

Thank you for proceeding with this RFE. I understand that including the '<' character could result it truncating a character from the end of the comment. However, the inclusion of the '<' character is what causes the comment to be associated with the preceding member of the struct, and so is really the crux of the RFE, so it's pretty vital! Thanks!

Hi, adding the extra '<' character should not be a problem with the understanding that there might be some truncation at the end of the comment in order to fit on allowed space.

We will be accepting this RFE. The RFE will be updated once put into plan. Thanks.

Thanks for the reply. We are reviewing your response and require a bit more time to evaluate it. This RFE will be updated accordingly.

Thank you for your reply. To be clear, the '<' is also required for the comment to be recognized by Doxygen as a documentation comment for the preceding variable, i.e.,

int var; /**< text of comment */

If the '<' is also part of your planned support for documentation comments, then we are OK with the one format.

Thanks!

Hi, we have been evaluating this RFE based on the information you provided.

Since Doxygen recognizes many different types of comment blocks the proposal is to implement only one enclosing format (due to resource constraints) that Doxygen supports namely, /**

May we know if you are okay with just one format? If okay, we shall go ahead and accept this RFE.

Hello,

I noticed that the status of this RFE is presently showing as "Need More Information". I thought I answered all questions in my comment on 2020-06-03, but would like to make sure. Please let me know of any further information that you may need.

Thanks, Gord Tomlin

Hello and thanks for the update.

Regarding the two limitations mentioned in your update:

1. Getting comments on zero-length items is a nice bonus. We do understand that the structural changes to the generated headers caused by a change from LEGACY to NOLEGACY would require review of all code using the generated headers. However, this is an answer to a different issue than that represented by this RFE.

2. While it would be nice to have the entirety of multi-line comments included in the generated headers, getting even the first comment line with the appropriate delimiters would be better than what we have today. We can live with this limitation. FYI, we switched to generating headers to RECFM=VB data sets so that there can be more room for comments without unduly enlarging the files.

In answer to your question, NOLEG would not be sufficient for our business needs. It does nothing to provide comments that are usable as input to a documentation generation app such as Doxygen.

Thanks!

We have reviewed the provided information. We do think this is a valid request, however, there would be two limitations mentioned below.

Consider this section of HLASM:

JSABCLR DS 0X Start of re-use clear area @410D001
JSABCLEV DS XL1 CREATING COMPONENT'S CODE LEVEL C
(JSABVRSN LAST TIME JSAB-CREATING C
CODE WAS UPDATED)

Corresponding output from current DSECT utility is as follow:
struct {
unsigned char _jsabclev; /* CREATING COMPONENT'S CODE LEVEL */
} jsabclr;

Requested output:
struct {
unsigned char _jsabclev; ///< CREATING COMPONENT'S CODE LEVEL
} jsabclr;

We would like to point out the following limitations:
1. Comments included for zero-length fields like JSABCLR above.
- This was actually fixed in V2R3 and up; and under the NOLEG (no legacy) option. Please consider using NOLEG option and switch to corrected output. NOLEG was introduced because the output was corrected but it might cause binary compatibility issues and will require to recompile any source using new struct definitions.

2. Multiple line comments like the one for field JSABCLEV. Only first line would be preserved.

Would using NOLEG be sufficient for your business use?

Thanks

Thank you for the additional info. We are reviewing your response.

Hi,

Thanks for the response.

First off, the web site for Doxygen has moved since this RFE was submitted. It's now at http://www.doxygen.nl/ [^] .
The section for documenting members of a struct is now here: http://www.doxygen.nl/manual/docblocks.html#memberdoc [^] .

Doxygen needs special characters in the comments in order to recognize them as documentation comments.

The following is a C++ style comment, but Doxygen will not use it:

int foo; // C++ style comment

The following is also a C++ style comment, and Doxygen will treat it as documentation:

int foo; ///< C++ style comment documenting the preceding member

Either the third slash (///) or an exclamation point (//!) is required to cause the comment to be recognized as a documentation comment. The less than sign is required to indicate that the comment refers to the member (foo in this example) preceding the comment.

Traditional C-style comments ( /* comment */ ) can be used as well, as long as extra characters are supplied to indicate a documentation comment and the "<" to indicate that the member being documented precedes the comment. For example, the following are valid documentation comments:

int var; /*!< Detailed description after the member */
int var; /**< Detailed description after the member */

For our own purposes, we would prefer to use the C++ comment syntax since it requires fewer total characters. However, what we are requesting (user-specifiable comment prefix and suffix) could be used to generate comments according to any preference and to satisfy the requirements of any other documentation production tool.

The following attachments from 2017-01-18 should include what you are requesting:

1. An assembler source file (RFE92319-SRC.txt) that generates a DSECT for IAZJSAB (from SYS1.MACLIB).

2. Sample JCL (RFE92319-JCL.txt) used to run EDCDSECT on the above source file.

3. A zip file (RFE92319-asis.zip) containing:
- src subdirectory with the header file as generated by EDCDSECT
- doc subdirectory produced by running Doxygen on the src subdirectory
- file Doxyfile containing the Doxygen settings to generate the doc.

4. A zip file (RFE92319-requested.zip) containing:
- src subdirectory with the header file generated by EDCDSECT, modified to preface the structure member comments with "///<" instead
of surrounding them with "/*" and "*/"
- doc subdirectory produced by running Doxygen on the src subdirectory
- file Doxyfile containing the Doxygen settings to generate the doc.

Please let me know if you require any further information. Thanks!

Hi,

While reviewing this RFE again, there were some additional questions:

We know certain comments within asm source were problematic since they were not preserved by ADATA records produced by HLASM which DSECT utility used to generate C-struct.
But we would like to get a better understanding of your usage.

Also can you please explain a bit more about the DOXYGEN comments, specially the 2nd one? ie:

int foo; ///< C++ style comment documenting the preceding member

It would be nice if you can give us a sample asm source and the output of DSECT utility with the manual modification of the comments you are looking for.
In addition, the URL link in the description does not work.

Thanks.

Thank you for your response. We are reviewing it and will update you once we have an answer.

Sorry, I must have missed the update requesting a sample testcase.

I have attached:

1. An assembler source file (RFE92319-SRC.txt) that generates a DSECT for IAZJSAB (from SYS1.MACLIB).

2. Sample JCL (RFE92319-JCL.txt) used to run EDCDSECT on the above source file.

3. A zip file (RFE92319-asis.zip) containing:
- src subdirectory with the header file as generated by EDCDSECT
- doc subdirectory produced by running Doxygen on the src subdirectory
- file Doxyfile containing the Doxygen settings to generate the doc.

4. A zip file (RFE92319-requested.zip) containing:
- src subdirectory with the header file generated by EDCDSECT,
modified to preface the structure member comments with "///<" instead
of surrounding them with "/*" and "*/"
- doc subdirectory produced by running Doxygen on the src subdirectory
- file Doxyfile containing the Doxygen settings to generate the doc.

Please let me know if you require any further information.

Attachment (Description): Project file used to run Doxygen with header file constructed by EDCDSECT manually modified to prefix comments with "///<" instead of surrounding them with "/*" and "*/". Header file is in src subdirectory. Generated documentation is in doc subdirectory.

Attachment (Description): Project file used to run Doxygen with header file as constructed by EDCDSECT. Header file is in src subdirectory. Generated documentation is in doc subdirectory.

Attachment (Description): JCL used to run EDCDSECT.

Attachment (Description): Source file used as input to EDCDSECT.

Hi, can you please provide a sample testcase that demonstrates your request?