From cd03c16477276ba423e04b7dca4789a21696df39 Mon Sep 17 00:00:00 2001 From: Floris Bruynooghe Date: Wed, 3 Jul 2024 10:22:49 +0200 Subject: [PATCH 1/5] docs: Reference rust doc style guide in contributing guidelines It is good for us to follow the common rust documentation style guide, so explicitly reference this guide. --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cd7c46dfd9..d5dffe1da5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow - **General code guidelines** - - When possible, please document relevant pieces of code. If documentation refers to another object (module, function, struct, etc) use ``[`path::to::ReferencedObject`]`` to link it. For more information check the [rustdoc docummentation][rustdoc] + - When possible, please document relevant pieces of code following the [rust documentation conventions][docconventtions]. For more information on how the rust documentation system works check the [rustdoc docummentation][rustdoc]. - Comment your code. It will be useful for your reviewer and future contributors. - **Pull request titles** @@ -100,3 +100,4 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow [forkiroh]: /~https://github.com/n0-computer/iroh/fork [draftprs]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests [rustdoc]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html +[docconventtions]: /~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text From be0b130ebbade4be4db7426da0f901f1e69fc713 Mon Sep 17 00:00:00 2001 From: Floris Bruynooghe Date: Wed, 3 Jul 2024 10:26:44 +0200 Subject: [PATCH 2/5] Also add this to the PR template --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 07937363dc..0c1872bec4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,6 +13,6 @@ ## Change checklist - [ ] Self-review. -- [ ] Documentation updates if relevant. +- [ ] Documentation updates following the [style guide][/~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text], if relevant. - [ ] Tests if relevant. - [ ] All breaking changes documented. From 2dd9f0e3bc111d84800558cd0e77e16aac8decec Mon Sep 17 00:00:00 2001 From: Floris Bruynooghe Date: Wed, 3 Jul 2024 10:31:58 +0200 Subject: [PATCH 3/5] typo in doc link name --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d5dffe1da5..e9f52c75c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow - **General code guidelines** - - When possible, please document relevant pieces of code following the [rust documentation conventions][docconventtions]. For more information on how the rust documentation system works check the [rustdoc docummentation][rustdoc]. + - When possible, please document relevant pieces of code following the [rust documentation conventions][docconventions]. For more information on how the rust documentation system works check the [rustdoc docummentation][rustdoc]. - Comment your code. It will be useful for your reviewer and future contributors. - **Pull request titles** @@ -100,4 +100,4 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow [forkiroh]: /~https://github.com/n0-computer/iroh/fork [draftprs]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests [rustdoc]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html -[docconventtions]: /~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text +[docconventions]: /~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text From a77657e728cb738409df17833ba2ca2d4d7f4dbd Mon Sep 17 00:00:00 2001 From: Floris Bruynooghe Date: Wed, 3 Jul 2024 13:52:51 +0200 Subject: [PATCH 4/5] markdown link fix Co-authored-by: Franz Heinzmann --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 0c1872bec4..f152cf0911 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,6 +13,6 @@ ## Change checklist - [ ] Self-review. -- [ ] Documentation updates following the [style guide][/~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text], if relevant. +- [ ] Documentation updates following the [style guide](/~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text), if relevant. - [ ] Tests if relevant. - [ ] All breaking changes documented. From a02b41cf43c645a9b1130ac45d1b1715bdb98ba4 Mon Sep 17 00:00:00 2001 From: Floris Bruynooghe Date: Wed, 3 Jul 2024 13:57:10 +0200 Subject: [PATCH 5/5] nicer link --- .github/pull_request_template.md | 2 +- CONTRIBUTING.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f152cf0911..6cc5a1f3ee 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,6 +13,6 @@ ## Change checklist - [ ] Self-review. -- [ ] Documentation updates following the [style guide](/~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text), if relevant. +- [ ] Documentation updates following the [style guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text), if relevant. - [ ] Tests if relevant. - [ ] All breaking changes documented. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9f52c75c0..b9d83651cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -100,4 +100,4 @@ Code contributions to Iroh are greatly appreciated. Here is the general workflow [forkiroh]: /~https://github.com/n0-computer/iroh/fork [draftprs]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests [rustdoc]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html -[docconventions]: /~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text +[docconventions]: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text