-
Notifications
You must be signed in to change notification settings - Fork 12.7k
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
Add docs about crate level documentation support #76289
Conversation
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see the contribution instructions for more information. |
Would it make sense to note that |
Yeah. I knew that but I thought it would be a more precise topic of its own. Anyway I will write a small paragraph on that in the rustdoc book and refile the PR |
I wrote all the details about the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the PR! A few quibbles with the wording but otherwise this looks great :)
Ok. Let's merge it then |
So finally I resolved your suggestions. Let's now merge this PR |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM but not sure if there's some other place this is documented already, leaving this to @steveklabnik
I think it's a nice add, however, it might be more interesting to talk about inner/outer attribute/doc comment rather just "crate documentation". After all, when using "//!" inside the crate module, you're documenting the top-level module. I think it'd make more sense to explain it like this (or link to the corresponding section because I'm pretty sure we already explained it) rather than just talk about "magical" crate documentation. |
As I said earlier, I thought of making it a precise topic on its own. Maybe later we can remove it and place it in its own page. But currently I just thought of putting it on the book. |
Like I said, I approve this add, but not its content. Saying "you can do this like that" is far better when you explain why it works like this so people can see and understand better the bigger picture. |
So, can you give me a better idea what should I do. Very thankful for that |
Sure! I'd give a small introduction about about to document a crate with "//!" and then say that it is an inner attribute and link to the corresponding section. Something along the line? |
Thank You. I will update the section to what you've said in a little while |
Ok I added stuff you suggested |
It seems that @steveklabnik has not shown any response to this PR. Therefore I think we should maybe change the assignee |
Can you please send a suggestion rather than a request change so that I can one-click commit them. Would he very nice if you do so |
@arijit79 you can make suggestions on your own PR |
I know that but I thought @steveklabnik could better highlight that |
Anyway how can I resolve these changes that are requested |
Ok. @steveklabnik. I tried to resolve all your requesting changes |
Looks good to me, further improvements can be done in follow-up PRs if necessary. Thanks so much for working on this! @bors r+ rollup |
📌 Commit 82d51873982a03eb7ec6019e32284d7f535568e1 has been approved by |
Sorry but I'll have to be annoying here. @arijit79: please squash your commits. r=me once done. @bors: r- |
You can do this like so: git rebase --root -i
# It will show a screen with all your commits; change all but the first from `pick` to `squash`
git push -f |
Thanks. I will try to do it ASAP |
I wrote a tutorial on how to squash here too. Like that you have two ways of doing it. ;) |
Hey guys. Just a support question. Basically I by mistake removed by rust repo and now I have to clone it again. But unfortunately it clones everything which is not part of my commits. Any idea what should I do |
If you removed the whole directory, there's no way to get it back except for running In the meantime I don't think this is worth blocking on. @bors r+ rollup |
📌 Commit 82d51873982a03eb7ec6019e32284d7f535568e1 has been approved by |
@bors r=jyn514 Squashed locally and pushed. |
📌 Commit fd5859a has been approved by |
Rollup of 11 pull requests Successful merges: - rust-lang#75857 (Syntactically permit unsafety on mods) - rust-lang#76289 (Add docs about crate level documentation support) - rust-lang#76514 (Add revisions to const generic issue UI tests.) - rust-lang#76524 (typeck: don't suggest inaccessible private fields) - rust-lang#76548 (Validate removal of AscribeUserType, FakeRead, and Shallow borrow) - rust-lang#76555 (Reword `trivial_casts` lint in rustc book to better explain what it does.) - rust-lang#76559 (add the `const_evaluatable_checked` feature) - rust-lang#76563 (small typo fix in rustc_parse docs) - rust-lang#76565 (take reference to Place directly instead of taking reference to Box<Place>) - rust-lang#76567 (use push(char) to add chars (single-char &strs) to strings instead of push_str(&str)) - rust-lang#76568 (Add missing examples on core traits' method) Failed merges: r? `@ghost`
Wrote information about how to write documentation on the crate level in rhe rustdoc book