Format UnfoldSim docstrings according to template #121
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Current templates: Function docstring template"""
my_function(argument1:Type1; keyword_argument3::Type3 = value3)
my_function(argument1::Type1, optional_argument2::Type2; keyword_argument3::Type3 = value3)
One-line description using the imperative form ("Do this") instead of the third person and ending with a period.
If the one-line description is not sufficient, one can also write a short paragraph with additional information.
# Arguments (if needed)
- `argument1::Type1`: Description of argument1.
- `optional_argument2::Type2` (optional): Description of optional_argument2.
# Keyword arguments (if needed)
- `keyword_argument3::Type3 = value3`: Description of keyword_argument3.
# Returns
- `result::Type4` : Description of result.
# Examples
```julia-repl
julia> my_function(value1, value2)
result1
julia> my_function(value1; keyword_argument3 = value4)
result2
```
See also [`my_function2`](@ref), [`my_function3`](@ref).
"""Type docstring template"""
MyType <: MyAbstractType
One-line desciption of my type which ends with a period.
If the one-line description is not sufficient, one can also write a short paragraph with additional information.
# Fields
- `field1::Type1`: Description of field1.
- `optional_field2::Type2` (optional): Description of field2. If not provided, defaults to `value2`.
# Examples
```julia-repl
julia> MyType(field1, field2)
result1
```
See also [`MyType2`](@ref), [`my_function2`](@ref).
""" |
jschepers
commented
Nov 25, 2024
| - `signal` : Generated signal. Depending on the design, on the components and on | ||
| `return_epoched`, the output can be a 1-D, 2-D, 3-D or 4-D Array. | ||
| For example, a 4-D Array would have the dimensions `channels x time x trials x subjects`. | ||
| - `events`: Generated events. |
There was a problem hiding this comment.
Suggested change
| - `events`: Generated events. | |
| - `events`: Generated events dataframe with latencies. |
jschepers
commented
Nov 25, 2024
| # Examples | ||
| Adapted from the quickstart tutorial in the UnfoldSim docs. | ||
| ```julia-repl | ||
| julia> using UnfoldSim |
There was a problem hiding this comment.
For the examples, you can omit the using UnfoldSim since the examples are for UnfoldSim functions.
jschepers
commented
Nov 25, 2024
| - `events`: Generated events. | ||
|
|
||
| # Examples | ||
| Adapted from the quickstart tutorial in the UnfoldSim docs. |
There was a problem hiding this comment.
Here you could put a link to the quickstart tutorial.
…nctions in the file.
…im.jl into improve-docstrings
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As pointed out by @cbrnr (#106), some of the docstrings are still incomplete and do not follow a common docstring convention. @cbrnr thanks a lot for pointing this out and for your suggestions on how to make the docstrings more consistent.
The goal is to transform the docstrings such that they match the docstring template, that I came up with based on the Julia manual, the Blue style guide and by checking the docstrings of other Julia packages.
I will post the current templates for
FunctionsandTypesbelow. However, please note that they are still subject to change when we find something that does not match the template.@maanikmarathe, here is a list of all UnfoldSim.jl
srcfiles with docstrings. Once we are done with them, we can check the boxes. Also, feel free to post about docstrings for which you are unsure how to format them or where information is missing, either in this issue (#108) or by writing to me on Zulip. As discussed, I started from the top of the list and would like you to start from the bottom.