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.

Sign up for GitHub

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

Jump to bottom

Add docs about crate level documentation support #76289

Merged
merged 1 commit into from
Sep 10, 2020
Merged

Add docs about crate level documentation support #76289

merged 1 commit into from
Sep 10, 2020

Conversation

AMythicDev
Copy link
Contributor

Wrote information about how to write documentation on the crate level in rhe rustdoc book

@rust-highfive
Copy link
Collaborator

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.

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 3, 2020
@Emilgardis
Copy link
Contributor

Emilgardis commented Sep 3, 2020 •
edited
Loading

Would it make sense to note that //! documents the contained item, and not just the crate?

Like in the book

@AMythicDev
Copy link
Contributor Author

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

@AMythicDev
Copy link
Contributor Author

I wrote all the details about the //! syntax in the book

@jyn514 jyn514 added A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Sep 3, 2020
jyn514
jyn514 reviewed Sep 3, 2020
View reviewed changes
Copy link
Member

@jyn514 jyn514 left a 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 :)

src/doc/rustdoc/src/what-is-rustdoc.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/what-is-rustdoc.md Outdated Show resolved Hide resolved
@AMythicDev
Copy link
Contributor Author

AMythicDev commented Sep 3, 2020 •
edited
Loading

Ok. Let's merge it then

@AMythicDev
Copy link
Contributor Author

AMythicDev commented Sep 3, 2020 •
edited
Loading

So finally I resolved your suggestions. Let's now merge this PR

@jyn514 jyn514 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 3, 2020
jyn514
jyn514 approved these changes Sep 4, 2020
View reviewed changes
Copy link
Member

@jyn514 jyn514 left a 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

@GuillaumeGomez
Copy link
Member

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.

@AMythicDev
Copy link
Contributor Author

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.

@GuillaumeGomez
Copy link
Member

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.

@AMythicDev
Copy link
Contributor Author

So, can you give me a better idea what should I do. Very thankful for that

@GuillaumeGomez
Copy link
Member

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?

@AMythicDev
Copy link
Contributor Author

Thank You. I will update the section to what you've said in a little while

@AMythicDev
Copy link
Contributor Author

Ok I added stuff you suggested

@AMythicDev
Copy link
Contributor Author

AMythicDev commented Sep 5, 2020 •
edited
Loading

It seems that @steveklabnik has not shown any response to this PR. Therefore I think we should maybe change the assignee

steveklabnik
steveklabnik suggested changes Sep 9, 2020
View reviewed changes
src/doc/rustdoc/src/what-is-rustdoc.md Show resolved Hide resolved
src/doc/rustdoc/src/what-is-rustdoc.md Outdated Show resolved Hide resolved
src/doc/rustdoc/src/what-is-rustdoc.md Outdated Show resolved Hide resolved
@AMythicDev
Copy link
Contributor Author

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

@jyn514
Copy link
Member

jyn514 commented Sep 9, 2020 •
edited
Loading

@arijit79 you can make suggestions on your own PR

@AMythicDev
Copy link
Contributor Author

I know that but I thought @steveklabnik could better highlight that

@AMythicDev
Copy link
Contributor Author

Anyway how can I resolve these changes that are requested

@AMythicDev
Copy link
Contributor Author

Ok. @steveklabnik. I tried to resolve all your requesting changes

@jyn514
Copy link
Member

jyn514 commented Sep 10, 2020

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

@bors
Copy link
Contributor

bors commented Sep 10, 2020

📌 Commit 82d51873982a03eb7ec6019e32284d7f535568e1 has been approved by jyn514

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 10, 2020
@GuillaumeGomez
Copy link
Member

Sorry but I'll have to be annoying here. @arijit79: please squash your commits. r=me once done.

@bors: r-

@bors bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Sep 10, 2020
@jyn514
Copy link
Member

jyn514 commented Sep 10, 2020

please squash your commits

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

@AMythicDev
Copy link
Contributor Author

AMythicDev commented Sep 10, 2020 •
edited
Loading

Thanks. I will try to do it ASAP

@GuillaumeGomez
Copy link
Member

I wrote a tutorial on how to squash here too. Like that you have two ways of doing it. ;)

@AMythicDev
Copy link
Contributor Author

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

@jyn514
Copy link
Member

jyn514 commented Sep 10, 2020

If you removed the whole directory, there's no way to get it back except for running git clone from scratch. Next time you're having trouble you could ask in #rustdoc or #t-compiler/help, you don't have to figure it out on your own :)

In the meantime I don't think this is worth blocking on.

@bors r+ rollup

@bors
Copy link
Contributor

bors commented Sep 10, 2020

📌 Commit 82d51873982a03eb7ec6019e32284d7f535568e1 has been approved by jyn514

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 10, 2020
@Mark-Simulacrum
Copy link
Member

@bors r=jyn514

Squashed locally and pushed.

@bors
Copy link
Contributor

bors commented Sep 10, 2020

📌 Commit fd5859a has been approved by jyn514

@jyn514 jyn514 mentioned this pull request Sep 10, 2020
Open
@tmandry tmandry mentioned this pull request Sep 10, 2020
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Sep 10, 2020
@bors
Auto merge of rust-lang#76582 - tmandry:rollup-lwwc93b, r=tmandry
ad3a6f7 
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`
@bors bors merged commit 91c3ef8 into rust-lang:master Sep 10, 2020
@rustbot rustbot added this to the 1.48.0 milestone Sep 10, 2020
@AMythicDev AMythicDev mentioned this pull request Sep 11, 2020
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jyn514 jyn514 jyn514 approved these changes

@steveklabnik steveklabnik steveklabnik requested changes

Assignees

@steveklabnik steveklabnik

Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.48.0
Development

Successfully merging this pull request may close these issues.
9 participants
@AMythicDev @rust-highfive @Emilgardis @GuillaumeGomez @jyn514 @bors @Mark-Simulacrum @steveklabnik @rustbot