Skip to main content

Block comments and Markdown

  • April 29, 2021
  • 5 replies
  • 0 views
A
  • Anonymous
Block comments are available in many programming languages and any lines of text between the start block and end block delimiters are considered part of the text. We are starting to use Markdown extensively in program headers for developer, modification history, program documentation, etc. It would be really helpful if U2 would implement this form of comment so that the Markdown text could be put in-line with the other documentation and we would not have to deal with leading comment marks.

An example might look like this:
​
The '***' on line 26 denotes a divider line in Markdown. A simple program can then strip the Markdown area and throw it to a temporary file to be viewed in your favorite browser or printed to a pdf. VSCode already supports Markdown preview and editing. Note that you can embed links to outside web documentation, internal code control resources (like VSTS) or documents in your file system.

I'd be curious to hear from the community if this would be helpful to others.

------------------------------
Jeff Teter
Woodforest National Bank
[Phone]
------------------------------

    5 replies

    David Green
    • David Green
    • Inspiring
    • 48 replies
    • April 29, 2021
    Block comments are available in many programming languages and any lines of text between the start block and end block delimiters are considered part of the text. We are starting to use Markdown extensively in program headers for developer, modification history, program documentation, etc. It would be really helpful if U2 would implement this form of comment so that the Markdown text could be put in-line with the other documentation and we would not have to deal with leading comment marks.

    An example might look like this:
    ​
    The '***' on line 26 denotes a divider line in Markdown. A simple program can then strip the Markdown area and throw it to a temporary file to be viewed in your favorite browser or printed to a pdf. VSCode already supports Markdown preview and editing. Note that you can embed links to outside web documentation, internal code control resources (like VSTS) or documents in your file system.

    I'd be curious to hear from the community if this would be helpful to others.

    ------------------------------
    Jeff Teter
    Woodforest National Bank
    [Phone]
    ------------------------------

    Wouldn't that be great!  But in the 26 years I've been programming Pick programmers just don't spend enough time commenting anything.  And when they do it is only a line or two.  Another programmer mentioned the other, "Oh it's self documenting."

     

    So not only do we need it, we need a whole mind shift to go with it!

     

    David

     


    A
    • Anonymous
    • 0 replies
    • April 29, 2021

    Wouldn't that be great!  But in the 26 years I've been programming Pick programmers just don't spend enough time commenting anything.  And when they do it is only a line or two.  Another programmer mentioned the other, "Oh it's self documenting."

     

    So not only do we need it, we need a whole mind shift to go with it!

     

    David

     


    Yes, hard habits to get into. But, with 5 or more developers here, we're trying to implement standards that make they work for the next guy more reasonable... So, with VSCode and snippets, we have a standard block for creating new program headers and documentation. Those then get captured to a 'PROGHELP' file that currently is html but is being converted over to Markdown. Certainly not a perfect solution, but it's a start...

    ------------------------------
    Jeff Teter
    Woodforest National Bank
    [Phone]
    ------------------------------
    J
    • Jeff Kendrick
    • New Participant
    • 1 reply
    • April 30, 2021
    Block comments are available in many programming languages and any lines of text between the start block and end block delimiters are considered part of the text. We are starting to use Markdown extensively in program headers for developer, modification history, program documentation, etc. It would be really helpful if U2 would implement this form of comment so that the Markdown text could be put in-line with the other documentation and we would not have to deal with leading comment marks.

    An example might look like this:
    ​
    The '***' on line 26 denotes a divider line in Markdown. A simple program can then strip the Markdown area and throw it to a temporary file to be viewed in your favorite browser or printed to a pdf. VSCode already supports Markdown preview and editing. Note that you can embed links to outside web documentation, internal code control resources (like VSTS) or documents in your file system.

    I'd be curious to hear from the community if this would be helpful to others.

    ------------------------------
    Jeff Teter
    Woodforest National Bank
    [Phone]
    ------------------------------
    You can leverage conditional compilation directives to insert multi-line comments right now.

    $ifdef BlockComment

    You can put whatever you want in here without REM, *, !, etc. at the beginning of each line.
    You can have code examples here, markdown text, anything at all.
    The compiler will ignore everything between $ifdef and $endif, as long as you don't have a
    line like this:  $define BlockComment

    $endif BlockComment

    This would also be quite easy for a pre-processor to handle for the purposes you've suggested. Also, you don't have to use "BlockComment" as the tag; you can use something shorter, like "$ifdef Com" just as effectively.

    ------------------------------
    Jeff Kendrick
    Personal
    ------------------------------
    A
    • Anonymous
    • 0 replies
    • April 30, 2021
    You can leverage conditional compilation directives to insert multi-line comments right now.

    $ifdef BlockComment

    You can put whatever you want in here without REM, *, !, etc. at the beginning of each line.
    You can have code examples here, markdown text, anything at all.
    The compiler will ignore everything between $ifdef and $endif, as long as you don't have a
    line like this:  $define BlockComment

    $endif BlockComment

    This would also be quite easy for a pre-processor to handle for the purposes you've suggested. Also, you don't have to use "BlockComment" as the tag; you can use something shorter, like "$ifdef Com" just as effectively.

    ------------------------------
    Jeff Kendrick
    Personal
    ------------------------------
    I like it! It's a handy method of achieving the goal.

    I'd still like to see block comments supported but this will work for now.

    Thanks!

    ------------------------------
    Jeff Teter
    Woodforest National Bank
    [Phone]
    ------------------------------
    A
    • Anonymous
    • 0 replies
    • April 30, 2021
    I like it! It's a handy method of achieving the goal.

    I'd still like to see block comments supported but this will work for now.

    Thanks!

    ------------------------------
    Jeff Teter
    Woodforest National Bank
    [Phone]
    ------------------------------
    Using Jeff Kendrick's suggestion, I'm providing here a sample program header (in JSON format) that can be added to your VSCode snippet file. Then, using VSCode with an empty document (or adding this to an existing for a retrofit), use <CTRL><space> to add the snippet. The snippet will stop and prompt the user for each of the items prefixed with "$" and it can re-use the same data for multiple spots in the documentation.

    Copy the lines between the "$ifdef BlockComment" and "$endif BlockComment" to a a new file and save it to your a file with a suffix of ".md". You can then open it in a browser (add the markdown preview extension, if needed) or VSCode has a good markdown viewer. 

    As mentioned above, you can include links, screen prints, etc. to improve your documentation and use the same documentation for help files.

    Note: The attached ".txt" file is actually a JSON string.

    I hope this helps someone else. Thanks, Jeff Kendrick for the simple fix...

    ------------------------------
    Jeff Teter
    Woodforest National Bank
    [Phone]
    ------------------------------


    Terms & ConditionsAccessibility statement