Open johnnychen94 opened 5 years ago
In https://github.com/JuliaImages/Images.jl/issues/772 and https://github.com/zygmuntszpak/ImageBinarization.jl/issues/23, we reach a consensus that a julia way of implementing image processing algorithm is to take advantage of multiple dispatch
abstract type BinarizationAlgorithm end
struct Otsu <: BinarizationAlgorithm end
struct Yen <: BinarizationAlgorithm end
function binarize(algo::Otsu, img)
# implementation
end
function binarize(algo::Yen, img)
# implementation
end
However, we will meet problem when writing docstring to each binarize
methods. Users will get pages of docstring with a single ?binarize
Why this is terrible?
?binarize
much more often than ?binarize(Otsu(),img)
Yen
when they're looking for docstring of Otsu
?binarize
The reason for this behavior is
When retrieving documentation for a generic function, the metadata for each method is concatenated with the catdoc function, which can of course be overridden for custom types.
One way to solve this problem is to
Otsu
, Yen
and etc. -- They're inherited type.In general, only the most generic method should be documented, or even the function itself (i.e. the object created without any methods by function bar end). Specific methods should only be documented if their behaviour differs from the more generic ones. In any case, they should not repeat the information provided elsewhere.
For example:
"""
Otsu()
one-line description
# Algorithm details
...
# Argument list
...
# Examples
...
# References
...
See also: [`binarize`](@ref ), [`BinarizationAlgorithm`](@ref)
"""
struct Otsu <: BinarizationAlgorithm end
"""
binarize(algo::Otsu, img)
one-line description
Check [`ImageBinarization.Otsu`](@ref ImageBinarization.Otsu) for more details
"""
function binarize(algo::Otsu, img)
# implementation
end
# In ImageBinarization.jl
"""
binarize(algo::BinarizationAlgorithm, img)
one-line description
detailed explaination
# Example
...
See also: [`BinarizationAlgorithm`](@ref)
"""
binarize
By doing this, we can get a more concise result with ?binarize
This is the continuation of https://github.com/JuliaImages/Images.jl/issues/767 on documentation style
!!! Warning ⚠️
This is not a guideline yet, at present it's just some material to inspire thoughts.
Why we need an extra documentation guide for Images.jl?
Many image processing algorithms are too complicated that well-explained documentations is absolutely necessary. The old way of documentation in other languages is to write step-by-step tutorials. For julia, Documenter.jl provides an alternative -- we can make everything documented in docstring, then the (step-by-step) tutorial of the function can be generated.
However, julia guide on documentation isn't prepared for this kind of docstring work -- most docstring in julia are quite small.
What part would this guide contain?
Based on julia documentation, a complete docstring contains:
detailed explaination
docstring with math
if you need to write math in your docstring, it's very likely that you need to write a huge mount of math, it's recommended to use
instead of
The former helps you debug your latex codes with your local latex compiler
One exception: if you just need some symbols, using Unicode (e.g.,
α
) is sufficient. -- REPL support unicode, but doesn't support latex.argument list
do I need an argument list?
You only need an detailed argument list when there is arguments that control the behavior and result of the function, otherwise, good design on names and method signature is enough.
argument list style
julia documentation uses the following style
we take another way,
This is because most arguments are too complicated to be explained using one-line sentence.
img
arugment(s)Most image processing functions have
img
argument(s):img
(e.g.,binarize(alg::Otsu, img::AbstractArray{T,2}) where T<: Colorant
), you don't need to explain it unless it's necessaryimg
arguments, (e.g.,ssd(img1, img2)
), you need to explain what eachimg
represents.code examples
the challenge with good-quality code example is:
jldoctest
with CI to make sure code example works as expected -- otherwise it might be a misleading.(TODO: Literate provides a way to write such kind of demos/tutorials, but I'm not sure if this works well with docstring examples.)
reference list
The following serves as a recommendation
APA style is not compulsory, the point is: you can't just simply provide an url link.
For example,
hints to related functions
syntax of
@ref
The following ways are recommended:
generic
with signature specified
with description
binarize
returns a binarized image usingBinarizationAlgorithm
Otsu
construct an instance ofOtsu
binarization algorithm.