From d4c43c026825f96b93b8b203393450ed6639a39b Mon Sep 17 00:00:00 2001 From: Floris Bruynooghe Date: Thu, 4 Jul 2024 11:41:07 +0200 Subject: [PATCH] docs: Reference rust doc style guide in contributing guidelines (#2452) ## Description It is good for us to follow the common rust documentation style guide, so explicitly reference this guide. ## Breaking Changes ## Notes & open questions I'm effectively introducing a new policy here. Feel free to discuss. ## Change checklist - [x] Self-review. - [x] Documentation updates if relevant. - ~~[ ] Tests if relevant.~~ - ~~[ ] All breaking changes documented.~~ --------- Co-authored-by: Franz Heinzmann --- .github/pull_request_template.md | 2 +- CONTRIBUTING.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 07937363dc..6cc5a1f3ee 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://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 cd7c46dfd9..b9d83651cc 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][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,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 +[docconventions]: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text