-
Notifications
You must be signed in to change notification settings - Fork 12.8k
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
Comments
Fully agree. Among the things it should cover:
|
I would like to aggregate all these ideas into a single draft document. What are your thoughts about it being an additional section to |
They should certainly be related. |
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 |
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 ;) |
Yes, it is something we should care about. I often spell things with British colour though 😅 |
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. |
This chapter covers writing documentation in depth. Fixes rust-lang#4361 Fixes rust-lang#12862 Fixes rust-lang#14070 Fixes rust-lang#14967
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.
We should have guidelines for how docs are written. Tense,
///
vs/**
, all that stuff.The text was updated successfully, but these errors were encountered: