Where to put field documentation

[danieldaeschle]

Short field docs are behind the field.

struct Bar {
    foo string // foo does something.
}

But what about long comments?
Last discussion with Alex was about moving it above if the comment is too long.

struct Bar {
    foo string // foo does something.
    // milk is different from foo because the comment is too long to put it behind the field. That's why it's on above the field.
    milk Milk
}

Does vdoc already handle this?

[larpon]

Long comments could also be split around first available white space at some length:

struct Bar {
    foo string // foo does something.
    // milk is different from foo because the comment is too long
    // so `vfmt` could break it at some length to put it behind the field.
    // That's why it's above the field.
    milk Milk
}

[larpon]

This would OFC not work with // extremely_long_connected_sentence_that_some_programmer_will_surely_use_to_get_around_it

[spytheman]

My first instinct while reading the above 'milk' comment is as a continuation of the previous line, just like lines in a book.
The commented area seem to me like one large block, not like 2 independent blocks, belonging first to the foo line, and the other to the milk line.

[larpon]

Oh yeah. Then we'd maybe need a newline between.

struct Bar {
    foo string // foo does something.

    // milk is different from foo because the comment is too long
    // so `vfmt` could break it at some length to put it behind the field.
    // That's why it's above the field.
    milk Milk
}

[spytheman]

btw, are there natural written languages, where reading direction changes in the middle of the page?

[danieldaeschle]

btw, are there natural written languages, where reading direction changes in the middle of the page?

😂 don‘t know

Nice opinion. What is your suggestion then for longer comments.

[danieldaeschle]

Btw. Most languages have doc string above. What about doing it always?

[larpon]

I don't think there is but now that it's on the internet - someone will probably go ahead and invent one just to keep us programmers on our toes 😅

[larpon]

I really like comments after the field BTW

[RiordanIX]

Historically, yes. It's called Boustrophedon. Basically not used in modern day except for some conlangs.