Skip to content

Add docs about crate level documentation support - #76289

Merged
bors merged 1 commit into
rust-lang:masterfrom
AMythicDev:master
Sep 10, 2020
Merged

Add docs about crate level documentation support#76289
bors merged 1 commit into
rust-lang:masterfrom
AMythicDev:master

Conversation

@AMythicDev

@AMythicDevAMythicDev commented Sep 3, 2020

Copy link
Copy Markdown
Contributor

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

@rust-highfive

rust-highfive commented Sep 3, 2020

Copy link
Copy Markdown
Contributor

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-highfiverust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 3, 2020
@Emilgardis

Emilgardis commented Sep 3, 2020•
edited
Loading

Copy link
Copy Markdown
Contributor

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

Like in the book

@AMythicDev

AMythicDev commented Sep 3, 2020

Copy link
Copy Markdown
ContributorAuthor

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

AMythicDev commented Sep 3, 2020

Copy link
Copy Markdown
ContributorAuthor

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

@jyn514jyn514 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

@jyn514jyn514 left a comment

Copy link
Copy Markdown
Member

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 :)

Comment threadsrc/doc/rustdoc/src/what-is-rustdoc.md Outdated
Comment threadsrc/doc/rustdoc/src/what-is-rustdoc.md Outdated
@AMythicDev

AMythicDev commented Sep 3, 2020•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Ok. Let's merge it then

jyn514
jyn514 reviewed Sep 3, 2020
View reviewed changes
Comment threadsrc/doc/rustdoc/src/what-is-rustdoc.md Outdated
@AMythicDev

AMythicDev commented Sep 3, 2020•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

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

@jyn514jyn514 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

@jyn514jyn514 left a comment

Copy link
Copy Markdown
Member

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

GuillaumeGomez commented Sep 4, 2020

Copy link
Copy Markdown
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

AMythicDev commented Sep 4, 2020

Copy link
Copy Markdown
ContributorAuthor

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

GuillaumeGomez commented Sep 4, 2020

Copy link
Copy Markdown
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

AMythicDev commented Sep 4, 2020

Copy link
Copy Markdown
ContributorAuthor

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

@GuillaumeGomez

GuillaumeGomez commented Sep 4, 2020

Copy link
Copy Markdown
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

AMythicDev commented Sep 4, 2020

Copy link
Copy Markdown
ContributorAuthor

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

@AMythicDev

AMythicDev commented Sep 4, 2020

Copy link
Copy Markdown
ContributorAuthor

Ok I added stuff you suggested

@AMythicDev

AMythicDev commented Sep 5, 2020•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

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
Comment threadsrc/doc/rustdoc/src/what-is-rustdoc.md Outdated
Comment threadsrc/doc/rustdoc/src/what-is-rustdoc.md Outdated
Comment threadsrc/doc/rustdoc/src/what-is-rustdoc.md Outdated
@AMythicDev

AMythicDev commented Sep 9, 2020

Copy link
Copy Markdown
ContributorAuthor

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

jyn514 commented Sep 9, 2020•
edited
Loading

Copy link
Copy Markdown
Member

@arijit79 you can make suggestions on your own PR

@AMythicDev

AMythicDev commented Sep 9, 2020

Copy link
Copy Markdown
ContributorAuthor

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

@AMythicDev

AMythicDev commented Sep 9, 2020

Copy link
Copy Markdown
ContributorAuthor

Anyway how can I resolve these changes that are requested

@AMythicDev

AMythicDev commented Sep 10, 2020

Copy link
Copy Markdown
ContributorAuthor

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

jyn514
jyn514 reviewed Sep 10, 2020
View reviewed changes
Comment threadsrc/doc/rustdoc/src/what-is-rustdoc.md Outdated
@jyn514

jyn514 commented Sep 10, 2020

Copy link
Copy Markdown
Member

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

bors commented Sep 10, 2020

Copy link
Copy Markdown
Collaborator

📌 Commit 82d51873982a03eb7ec6019e32284d7f535568e1 has been approved by jyn514

@borsbors 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

GuillaumeGomez commented Sep 10, 2020

Copy link
Copy Markdown
Member

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

@bors: r-

@borsbors 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

jyn514 commented Sep 10, 2020

Copy link
Copy Markdown
Member

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

AMythicDev commented Sep 10, 2020•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Thanks. I will try to do it ASAP

@GuillaumeGomez

GuillaumeGomez commented Sep 10, 2020

Copy link
Copy Markdown
Member

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

@AMythicDev

AMythicDev commented Sep 10, 2020

Copy link
Copy Markdown
ContributorAuthor

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

jyn514 commented Sep 10, 2020

Copy link
Copy Markdown
Member

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

bors commented Sep 10, 2020

Copy link
Copy Markdown
Collaborator

📌 Commit 82d51873982a03eb7ec6019e32284d7f535568e1 has been approved by jyn514

@borsbors 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

Mark-Simulacrum commented Sep 10, 2020

Copy link
Copy Markdown
Member

@bors r=jyn514

Squashed locally and pushed.

@bors

bors commented Sep 10, 2020

Copy link
Copy Markdown
Collaborator

📌 Commit fd5859a has been approved by jyn514

@jyn514jyn514 mentioned this pull request Sep 10, 2020
Closed
@tmandrytmandry 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 ofrust-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:masterSep 10, 2020
@rustbotrustbot added this to the 1.48.0 milestone Sep 10, 2020
@AMythicDevAMythicDev mentioned this pull request Sep 11, 2020
Closed
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

2 more reviewers
@jyn514jyn514jyn514 approved these changes
@steveklabniksteveklabniksteveklabnik requested changes
Reviewers whose approvals may not affect merge requirements

Assignees

@steveklabniksteveklabnik

Labels

A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsS-waiting-on-borsStatus: Waiting on bors to run and complete tests. Bors will change the label on completion.T-rustdocRelevant 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