Multiline comments about millfork

[james7780]

You can comment out a block (with // comments) in VS Code using Ctrl-K-C, similar block commenting is available in other editors.

There's probably a good reason for not having /* and */ , I just cant remember what it is :)

[KarolS]

The reasons for not having block comments are having to decide:

• what to do with nested comments
• what to do when an end-of-comment token occurs inside a (potentially malformed) string literal

Both those issues are important when using block comments to comment out code, but can also occur in artificial one-line examples:

/*  xxx /* xxx */ is this commented out or not? */

/* " */ is this commented out or not? " */

Right now, the closest Millfork has to block comments is the preprocessor; usually, you can wrap a piece of text in

#if 0
...
#endif

This nests and doesn't break because of strings, however due to being a preprocessor feature, it does not allow for certain tricky techniques a native comment feature would.

I would love some feedback:

• would Millfork improve by having block comments?
• should block comments nest?
• should the end token stand on its own line, to prevent various parsing issues?
• should the start token?
• what should the syntax look like?
• should Millfork get a standard documentation comment syntax?

[james7780]

Like you say, the #if 0 ... #endif can be used instead of /* / when debugging, personally feel / */ is unnecessary.

Regarding standard documentation comment syntax, I already use /// in my code where I think I might want to use doxygen in the future.

[oziphantom]

I tried Ctrl-K-C but I think because I have the millfork cx16 installed it doesn't work anymore. Maybe something needs to define what the comment char for 'millfork' is for it?

#if 0 is probably fine for code blocking. The benefit I see for /* is a lot of things will see it and know that it is a comment and colour it as such, while preprocessor #if defs don't get coloured or understood by normal text editors or even complex ones like xcode.

/* xxx /* xxx / is this commented out or not? /
/ xxx / xxx */ - is the comment
is this commented out or not? */ - not commented
inside " comments are not dealt with, for example I would also expect
"this is normal // this is still not commented " to work.
Follow C/C++ rules as that is what most text editors will do.

It also allows for context.
#if is now a code level construct and used to allow conditional code/handle multiple platforms etc
/* this is not code and is a comment, and should be considered as such

For example compare the visual structure of these two

#if C64
    #if 0
        This will set the memory map to just IO
        Also disables the CIA IRQ/NMI
    #endif
    lda #$35
    sta $01
#endif
#if C128
    #if 0
        This will set the memory map to just IO Block 0 RAM
        Zero Page will be 0:0000
        Stack Page will be 0:1000
        VIC block will be 0
        Also disables the VIC IRQ
    #endif
    lda #$fe
    sta $ff00
    lda #0
    sta $d01a
    sta $d506
    sta $d50A
    sta $d508
    sta $d507
    lda #1
    sta $d509
    lda $d019
    sta $d019
#endif
#if Mega65
    #if 0
        This will set the memory map to just IO with no higher ram mapped
        Z register will be reset to 0
        Base Page is set to 0
        Also disables the CIA IRQ/NMI
    #endif
    [$a9,$00,$aa,$a8,$4b,$5c,$ea,$5b]
#endif
#if C64 || Mega65
    lda #$7f
    sta $dc0d
    sta $dd0d
    lda $dc0d
    lda $dc0d
#endif


#if C64
    /*
        This will set the memory map to just IO
        Also disables the CIA IRQ/NMI
    */
    lda #$35
    sta $01
#endif
#if C128
    /*
        This will set the memory map to just IO Block 0 RAM
        Zero Page will be 0:0000
        Stack Page will be 0:1000
        VIC block will be 0
        Also disables the VIC IRQ
    */
    lda #$fe
    sta $ff00
    lda #0
    sta $d01a
    sta $d506
    sta $d50A
    sta $d508
    sta $d507
    lda #1
    sta $d509
    lda $d019
    sta $d019
#endif
#if Mega65
    /*
        This will set the memory map to just IO with no higher ram mapped
        Z register will be reset to 0
        Base Page is set to 0
        Also disables the CIA IRQ/NMI
    */
    [$a9,$00,$aa,$a8,$4b,$5c,$ea,$5b]
#endif
#if C64 || Mega65
    lda #$7f
    sta $dc0d
    sta $dd0d
    lda $dc0d
    lda $dc0d
#endif

[agg23]

I apologize for the delay in responding. As part of my LSP work in #81 I implemented multiline comments in an attempt to conform to the JSDoc style of creating docstrings. As @KarolS correctly mentions, my implementation suffers from the comment termination and string handling issue, though I'm not sure how problematic these actually are. In my opinion, the value brought along with multiline comments (though really just any kind of automated doccomments) outweighs the compile errors that may occur due to difficult to parse scenarios. I don't think that it is possible to successfully build with one of the above scenarios.

In any case, as long as errors are thrown, I think that should be sufficient for now. As we start adding more featureful LSP support (such as highlighting compile errors in editor), the improved iteration time should make any such errors largely a non-issue.