From 5c552f395afdf9aa266585b50624baf1418d23f1 Mon Sep 17 00:00:00 2001 From: Christian Kurz Date: Wed, 20 Sep 2017 08:33:05 +0200 Subject: [PATCH 1/8] Added "Provide hints to similar functions" This PR proposes a standard wording for hints to similar functions. Feel free to correct and change! --- doc/src/manual/documentation.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 289bdbb30f0d2..b9af9afc665ef 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -81,7 +81,23 @@ As in the example above, we recommend following some simple conventions when wri ... """ ``` -5. Include any code examples in an `# Examples` section. +5. Provide hints to similar functions + + Sometimes there are functions of similar functionality, which are named quite different. To increase + discoverability please provide a short list of these similar functions in a `See also: ` section. + + ``` + See also: bar!, baz, baaz + ``` + If the difference in functionality is not obvious from the name, you can provide a short description + in a list: + + ``` + See also: bar! - mutating variant, see for description of keyword arguments + baz - is an extraordinary example + baaz - even more marvellous + ``` +6. Include any code examples in an `# Examples` section. Examples should, whenever possible, be written as *doctests*. A *doctest* is a fenced code block (see [Code blocks](@ref)) starting with ````` ```jldoctest````` and contains any number of `julia>` @@ -127,13 +143,13 @@ As in the example above, we recommend following some simple conventions when wri !!! tip Wherever possible examples should be **self-contained** and **runnable** so that readers are able to try them out without having to include any dependencies. -6. Use backticks to identify code and equations. +7. Use backticks to identify code and equations. Julia identifiers and code excerpts should always appear between backticks ``` ` ``` to enable highlighting. Equations in the LaTeX syntax can be inserted between double backticks ``` `` ```. Use Unicode characters rather than their LaTeX escape sequence, i.e. ``` ``α = 1`` ``` rather than ``` ``\\alpha = 1`` ```. -7. Place the starting and ending `"""` characters on lines by themselves. +8. Place the starting and ending `"""` characters on lines by themselves. That is, write: @@ -156,7 +172,7 @@ As in the example above, we recommend following some simple conventions when wri ``` This makes it more clear where docstrings start and end. -8. Respect the line length limit used in the surrounding code. +9. Respect the line length limit used in the surrounding code. Docstrings are edited using the same tools as code. Therefore, the same conventions should apply. It it advised to add line breaks after 92 characters. From bc57c0d7d187d439446878f0e7de7ccb98194b16 Mon Sep 17 00:00:00 2001 From: Christian Kurz Date: Wed, 20 Sep 2017 09:32:10 +0200 Subject: [PATCH 2/8] added ms-list formatting, ref-links --- doc/src/manual/documentation.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index b9af9afc665ef..f587062d06386 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -87,15 +87,17 @@ As in the example above, we recommend following some simple conventions when wri discoverability please provide a short list of these similar functions in a `See also: ` section. ``` - See also: bar!, baz, baaz + See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) ``` If the difference in functionality is not obvious from the name, you can provide a short description in a list: ``` - See also: bar! - mutating variant, see for description of keyword arguments - baz - is an extraordinary example - baaz - even more marvellous + See also: + + * [`bar!`](@ref) - mutating variant, see for description of keyword arguments + * [`baz`](@ref) - is an extraordinary example + * [`baaz`](@ref) - even more marvellous ``` 6. Include any code examples in an `# Examples` section. From 5c872be60db2e6e986de366caff6c9df40fc9b04 Mon Sep 17 00:00:00 2001 From: Christian Kurz Date: Wed, 20 Sep 2017 11:38:05 +0200 Subject: [PATCH 3/8] Removed short description style --- doc/src/manual/documentation.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index f587062d06386..1b91e982fe7de 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -89,16 +89,6 @@ As in the example above, we recommend following some simple conventions when wri ``` See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) ``` - If the difference in functionality is not obvious from the name, you can provide a short description - in a list: - - ``` - See also: - - * [`bar!`](@ref) - mutating variant, see for description of keyword arguments - * [`baz`](@ref) - is an extraordinary example - * [`baaz`](@ref) - even more marvellous - ``` 6. Include any code examples in an `# Examples` section. Examples should, whenever possible, be written as *doctests*. A *doctest* is a fenced code block From c4a405b99feebc71035176dcf6173d7ce557d67e Mon Sep 17 00:00:00 2001 From: Christian Kurz Date: Wed, 20 Sep 2017 11:40:15 +0200 Subject: [PATCH 4/8] Added frederiks corrections --- doc/src/manual/documentation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 1b91e982fe7de..147a091b8a813 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -83,8 +83,8 @@ As in the example above, we recommend following some simple conventions when wri ``` 5. Provide hints to similar functions - Sometimes there are functions of similar functionality, which are named quite different. To increase - discoverability please provide a short list of these similar functions in a `See also: ` section. + Sometimes there are functions of related functionality. To increase discoverability please provide + a short list of these in a `See also: ` section. ``` See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) From 172a528dd9c80ad69f4f7d3de4377a5631cbb7bc Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Wed, 20 Sep 2017 12:10:03 +0200 Subject: [PATCH 5/8] whitespace --- doc/src/manual/documentation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 147a091b8a813..c779d95e786c3 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -82,10 +82,10 @@ As in the example above, we recommend following some simple conventions when wri """ ``` 5. Provide hints to similar functions - + Sometimes there are functions of related functionality. To increase discoverability please provide a short list of these in a `See also: ` section. - + ``` See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) ``` From bb43799df4f1a64d6ac1cb94cb3c8ef5030e363a Mon Sep 17 00:00:00 2001 From: Christian Kurz Date: Thu, 21 Sep 2017 08:48:25 +0200 Subject: [PATCH 6/8] Bold `See also`, add newline, wording suggestions --- doc/src/manual/documentation.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index c779d95e786c3..50cac111b413b 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -81,13 +81,14 @@ As in the example above, we recommend following some simple conventions when wri ... """ ``` -5. Provide hints to similar functions +5. Provide hints to related functions. Sometimes there are functions of related functionality. To increase discoverability please provide - a short list of these in a `See also: ` section. + a short list of these in a `**See also:**` paragraph. ``` - See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) + **See also:** + [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) ``` 6. Include any code examples in an `# Examples` section. From 2124d89b4162f3b75ec90151fd263071a0fed876 Mon Sep 17 00:00:00 2001 From: Christian Kurz Date: Mon, 25 Sep 2017 10:24:25 +0200 Subject: [PATCH 7/8] Removed bold --- doc/src/manual/documentation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 50cac111b413b..3146c4150d38c 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -84,11 +84,10 @@ As in the example above, we recommend following some simple conventions when wri 5. Provide hints to related functions. Sometimes there are functions of related functionality. To increase discoverability please provide - a short list of these in a `**See also:**` paragraph. + a short list of these in a `See also:` paragraph. ``` - **See also:** - [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) + See also:[`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) ``` 6. Include any code examples in an `# Examples` section. From c20f02d2bd1d75b5bd6deb953f9cecf499d8926a Mon Sep 17 00:00:00 2001 From: Kristoffer Carlsson Date: Mon, 25 Sep 2017 10:29:09 +0200 Subject: [PATCH 8/8] fix colon --- doc/src/manual/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 3146c4150d38c..4fb81ae1f1150 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -87,7 +87,7 @@ As in the example above, we recommend following some simple conventions when wri a short list of these in a `See also:` paragraph. ``` - See also:[`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) + See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref) ``` 6. Include any code examples in an `# Examples` section.