if a function's return type had a doc comment would it wear it like this fn foo() -> /// docs String { } or like this fn foo() /// docs -> String { }
-
Good points. I like the split format for being easy to scan while reading the code, and (at the opposite of your comment) able to be folded selectively, but perhaps smarter syntax handling with an awareness of the markdown would solve these instead
yeah, being easy to scan is super important. that's why in my examples the parameters have one-line docs, and I'd put overarching concepts into their own sections. using markdown highlighting for comment content would be neat! even just for **bold** and _italic_ stuff :)
-
-
I feel like this example of behaviour depending on what arg it is highlights the possibilities of having targeted parameter docs otherwise it's either all in the common, with phrasing worries, or repetitive with refs to commons but this is a weak feel, not sure either way
-
more importantly I think a mockup of how it would render would help (either version), because how they are consumed does inform how the docs are written...
@QuietMisdreavus -
are you asking about the "machine-parseable markdown" concept? i wouldn't change the *rendering* at all - i'd just have rustdoc do exhaustiveness checking and leave it at that
-
for doc comments applied to args/typarams/ret types, i'd add additional headers underneath the general prose if such docs existed
-
hmm so in the end it would render like the machine-markdown version? kinda?
-
pretty much, yeah
-
I'm of either mind, then. I like the feel and look of the individual blocks, but I think a (third-party) macro would work better (at least for now) to achieve this avoids changing the parser, backward compat, lets things evolve faster, leaves choice open interesting concept tho
End of conversation
New conversation -
Loading seems to be taking a while.
Twitter may be over capacity or experiencing a momentary hiccup. Try again or visit Twitter Status for more information.