From 7bf55a807dc173421ffeb3f42ab6aaf99ed709a9 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Tue, 31 May 2022 15:56:40 -0700 Subject: [PATCH 1/2] fix broken links --- src/SUMMARY.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7a07dad..ea8164f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -48,8 +48,8 @@ - [Documentation](./documentation/summary.md) - [doc alias policy](./documentation/doc-alias-policy.md) - [safety comments policy](./documentation/safety-comments.md) - - [how to write documentation](./how-to-write-documentation.md) - - [reviewing doc changes](./reviewing-doc-changes.md) + - [how to write documentation](./documentation/how-to-write-documentation.md) + - [reviewing doc changes](./documentation/reviewing-doc-changes.md) --- From 0b89f946bb586f77ad803decda0200f23389d638 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 2 Jun 2022 11:32:54 +0200 Subject: [PATCH 2/2] Fix code blocks --- .../how-to-write-documentation.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/documentation/how-to-write-documentation.md b/src/documentation/how-to-write-documentation.md index d3827ee..2c88147 100644 --- a/src/documentation/how-to-write-documentation.md +++ b/src/documentation/how-to-write-documentation.md @@ -60,9 +60,11 @@ blocks by default). It allows us to know if the documentation is up to date. As such, please avoid using `ignore` as much as possible on code blocks! If you want as a language other than Rust, simply set it in the code block tags: - ```text - This is not rust code! - ``` +````text +```text +This is not rust code! +``` +```` Some special cases: * If the code example cannot be run (when documenting a I/O item for example), @@ -99,7 +101,7 @@ The basic format of each documented methods/functions should roughly look like t By `explanations` we mean that the text should explain what the method and what each of its arguments are for. Let's take this method for example: -```rust +```rust,ignore pub fn concat_str(&self, s: &str) -> String { if s.is_empty() { panic!("empty concat string"); @@ -134,12 +136,14 @@ It is better if you use `assert*!` macros at the end to ensure that the example is working as expected. It also allows the readers to understand more easily what the function is doing (or returning). - # Examples +````text +# Examples - ``` - let s = MyType::new("hello "); - assert_eq!("hello Georges", s.concat_str("Georges").as_str()); - ``` +``` +let s = MyType::new("hello "); +assert_eq!("hello Georges", s.concat_str("Georges").as_str()); +``` +```` ## How to write documentation for other items