Add docstrings for exported functions and types #59
Conversation
|
Is this project still active? |
src/NIfTI.jl
Outdated
| """ | ||
| NIVolume{T<:Number,N,R} <: AbstractArray{T,N} | ||
| An `N`-dimensional NIfTI volume, with raw data of type | ||
| `R`. Note that if `raw <: Number`, it will be converted to `Float32`. Additionally, the header is automatically |
There was a problem hiding this comment.
| `R`. Note that if `raw <: Number`, it will be converted to `Float32`. Additionally, the header is automatically | |
| `R`. Note that if `R <: Number`, it will be converted to `Float32`. Additionally, the header is automatically |
Also there is no antecedant for "it"---presumably you're referring to T but that hasn't been described. It's also confusing: if the user creates the type with a specific T that T must be used exactly as specified. I think you're conflating the type documentation with the constructor, which in the absence of a manually-specified T does indeed use promotion to compute a type compatible with floating-point arithmetic.
There was a problem hiding this comment.
You're right, I was referring to the behavior of the constructor on line 131. Is it preferable to document constructor behavior in a separate docstring?
There was a problem hiding this comment.
I think it would be great to document the constructor too. But you can bundle it with the type into a single docstring, just cleanly specify whether you're talking about the type or the constructor.
Sometimes I just document the constructor and leave the type as an undocumented internal detail.
Co-authored-by: Tim Holy <[email protected]>
|
@timholy Thanks for the review! Julia is such a great language for neuroimaging work, and I'd love to help grow the ecosystem. |
|
How often are people actively mutating fields in the header? I'd prefer that users not muck around with the header unless they really know what is going on and I'd like to just remove this type and attach an immutable header to |
Added docstrings for the exported functions and types. This should make the package a bit more friendly to use, since currently the only way to access much of the documentation is by looking at the source comments.