expand comments section #2
Conversation
| documentation that you would like to be included in Rustdoc's output. | ||
| They support | ||
| [Markdown syntax](http://daringfireball.net/projects/markdown/) | ||
| and are the main way of documenting your code. |
There was a problem hiding this comment.
"the main way of documenting your public APIs" would be a bit more precise.
|
This is great, thanks so much for contributing! I've made a couple of minor comments -- if you could update the PR accordingly, I'd be happy to merge it. |
|
Updated. Let me know if you have more to add. |
| These blocks should be simple enough to demonstrate the feature and | ||
| give some context on how to use it. | ||
|
|
||
| Imports should generally be module-qualified, for example: |
There was a problem hiding this comment.
I think this is redundant with the section on imports (style/imports.html) -- is there something beyond those general guidelines that particularly applies to code snippets in doc comments?
There was a problem hiding this comment.
Nah, I'll just nix it for now and leave it as "open" for now - since we might have something decent to say about it, but I haven't thought of it.
|
Changed - I removed the bits about code snippets, just leaving it as "open" for now. Edit: Or, does this change the whole section to "open" if there's an unanswered section? We could either:
|
|
I think it's fine to leave [RFC] at the top, [OPEN] within for now; we'll get more formal about the status stuff later on. Thanks again! |
I did some work on expanding the comments guidelines.
Any feedback is appreciated.