Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Guide: how to write docs. #14070

Closed
steveklabnik opened this issue May 9, 2014 · 8 comments · Fixed by #22549
Closed

Guide: how to write docs. #14070

steveklabnik opened this issue May 9, 2014 · 8 comments · Fixed by #22549

Comments

@steveklabnik
Copy link
Member

We should have guidelines for how docs are written. Tense, /// vs /**, all that stuff.

@lilyball lilyball added the A-docs label May 9, 2014
@lilyball
Copy link
Contributor

lilyball commented May 9, 2014

Fully agree. Among the things it should cover:

  • What a docstring is
  • First paragraph is summary
  • Summary should usually be a single sentence, and should always have a trailing period
    • At least for functions. Our modules almost never have the trailing period. That seems ok to me, but it's all subjective
  • Tense, e.g. "Create a Foo" vs "Creates a Foo"
    • Tense in summary different than tense in rest of documentation? It sometimes is. Is that ok?
  • Proper use of inline code spans whenever referencing e.g. types, variables
  • Proper use of code blocks (```, not ~~~~)
  • Code block modifiers, e.g. rust, ignore, notrust
  • Common headers seen in docstrings, e.g. # Example, # Failure

@alxgnon
Copy link
Contributor

alxgnon commented May 12, 2014

I would like to aggregate all these ideas into a single draft document. What are your thoughts about it being an additional section to doc/rustdoc.md? I believe that document needs a lot of work, and adding a rustdoc style guide would help greatly.

@steveklabnik
Copy link
Member Author

They should certainly be related.

@treeman
Copy link
Contributor

treeman commented Jul 16, 2014

It would be nice if we could settle on these things. I want to contribute to the documentation and I end up mimicking the current style in the source files, but that style differs.

There's also the issue of # Example vs ## Example, see #15499.

@carols10cents
Copy link
Member

I don't know if this is something we care about, but if there is a preference towards British or American spelling, I think it should be a stated part of this guide. Sceptical is what made me think of this (<3 @steveklabnik ;)

@steveklabnik
Copy link
Member Author

Yes, it is something we should care about. I often spell things with British colour though 😅

@lilyball
Copy link
Contributor

Good point. My belief is that the documentation to date has been using american spelling, because I feel like I would remember if I saw British spelling in it. It would be good to codify this. Personally, I don't care which spelling rules are chosen as long as it's consistent, but given that I believe the docs are using american spelling right now, I would suggest sticking with that.

steveklabnik added a commit to steveklabnik/rust that referenced this issue Mar 4, 2015
This chapter covers writing documentation in depth.

Fixes rust-lang#4361
Fixes rust-lang#12862
Fixes rust-lang#14070
Fixes rust-lang#14967
bors added a commit that referenced this issue Mar 7, 2015
This chapter covers writing documentation in depth.

Fixes #4361
Fixes #12862
Fixes #14070
Fixes #14967
bors added a commit to rust-lang-ci/rust that referenced this issue Feb 13, 2023
Implement proc-macro-api versioning

So as it stands, we can't really change the proc-macro-api protocol at all without breaking all proc-macro servers again. To somewhat alleviate this we can move the supported ABI mess over to the proc-macro-api now by supporting multiple versions there (versions defined by us at least, not by rustc). Since the proc-macro-api protocol has no versioning scheme at the moment though, the best we can do here is add a new request to query the version from a server. Due to how the server currently works though, if it encounters an unknown request it will exit, meaning we can check if it is a server without support by checking if it exited after our version check request, that way we can support the current circulating server as well.

We need this since our span type will change from `TokenId` to something else at some point, but for that to work we need to comply with that the server expects. So knowing the version the server is using we can decide whether to send our new span data, or the tokenid (assuming we keep that information with our span data as well, alternatively we send irrelevant tokenids). That way we can keep old servers working while the user installations slowly migrate to newer servers that support the new spandata.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants