Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added "Provide hints to similar functions" #23788

Merged
merged 8 commits into from
Sep 25, 2017
Merged

Added "Provide hints to similar functions" #23788

Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5c552f3
Added "Provide hints to similar functions"
Sep 20, 2017
bc57c0d
added ms-list formatting, ref-links
Sep 20, 2017
5c872be
Removed short description style
Sep 20, 2017
c4a405b
Added frederiks corrections
Sep 20, 2017
172a528
whitespace
fredrikekre Sep 20, 2017
bb43799
Bold `See also`, add newline, wording suggestions
Sep 21, 2017
2124d89
Removed bold
Sep 25, 2017
c20f02d
fix colon
KristofferC Sep 25, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions doc/src/manual/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,16 @@ 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 related functions.

Sometimes there are functions of related functionality. To increase discoverability please provide
a short list of these in a `**See also:**` paragraph.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer ditching the boldness here, it draws attention from the docstring.

Copy link
Contributor Author

@ChristianKurz ChristianKurz Sep 21, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right, the newline should be enough.

I updated the pop!, push! etc. docs to comply with these rules.
I kind of like the boldness better than the newline, though. Any further comments?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have a strong opinion regarding the bold, but we probably don't need a new line after "See also". A line break before it should be enough IMHO.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the bold looks ugly. With a new line, you mean an empty line between the docstring and "See also" right? Just a new line won't render as a such.

julia> """
           foo

       Calculate foo.
       See also: `bar`
       """
       foo
foo

help?> foo
search: floor pointer_from_objref OverflowError RoundFromZero FileMonitor functionloc StackOverflowError @functionloc Factorization OutOfMemoryError unsafe_pointer_to_objref default_worker_pool

  foo

  Calculate foo. See also: bar

vs

julia> """
           foo

       Calculate foo.

       See also: `bar`
       """
       foo
foo

help?> foo
search: floor pointer_from_objref OverflowError RoundFromZero FileMonitor functionloc StackOverflowError @functionloc Factorization OutOfMemoryError unsafe_pointer_to_objref default_worker_pool

  foo

  Calculate foo.

  See also: bar


```
**See also:**
[`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref)
```
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>`
Expand Down Expand Up @@ -127,13 +136,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:

Expand All @@ -156,7 +165,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.
Expand Down