search

JuliaImages / ImageFiltering.jl

Julia implementations of multidimensional array convolution and nonlinear stencil operations
Other
99 stars 49 forks source link

Fix/update imgradients documentation #136

Closed stillyslalom closed 4 years ago

codecov[bot] commented 4 years ago

Codecov Report

Merging #136 into master will not change coverage. The diff coverage is n/a.

Impacted file tree graph

@@           Coverage Diff           @@
##           master     #136   +/-   ##
=======================================
  Coverage   84.98%   84.98%           
=======================================
  Files           9        9           
  Lines        1172     1172           
=======================================
  Hits          996      996           
  Misses        176      176
Impacted Files Coverage Δ
src/specialty.jl 93.75% <ø> (ø) :arrow_up:

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 698a92b...b47f512. Read the comment docs.

timholy commented 4 years ago

I've requested a review from @zygmuntszpak

stillyslalom commented 4 years ago

Tangentially related: the full block of documentation text (including LaTeX) is printed in response to ?imgradients, which stretches for 12 pages when pasted into Word. I'd like to refactor the documentation to make the command line help more succinct, leaving the full explanation for web only, but I'm not familiar with how the auto-doc generator works. Any pointers?

zygmuntszpak commented 4 years ago

It might be worth opening a new issue for that. The documentation is built with Documenter.jl. You may also want to read the relevant section in the Julia manual.

The documentation is lifted from the docstring associated with the function so its what you see for both the console and online. I wrote the documentation with a primarily online reading audience in mind, but people that read it from the console don't like it because it looks ugly and long in the console.

There are also two different philosophies when it comes to the documentation. Some want a minimalist approach, where the documentation is described as tersely as possible, whereas I aim for more detail so that a user of the API can have a better understanding of what the algorithm actually does. I think @johnnychen94 is in (your?) terse camp. One compromise we have been thinking about is to make use of his DemoCards project and to put the detailed explanation of the algorithm and its parameters in a demo, and link to it from the docstring. It took a long time and effort to write the documentation, so I would prefer if it didn't just disappear into the ether...

johnnychen94 commented 4 years ago

Yes, I prefer to have shorter console docstrings and move those lengthy explanations to HTML.

FYI, some current (not well-built) examples using DemoCards are:

More specifically, the idea is to host the docstring, the detailed explanation, and the demo codes in these cards. But to do this I need to make DemoCards.jl better first so that I'm not the only user of it 😄

timholy commented 4 years ago

The lengthy docstrings here are the impetus for https://github.com/JuliaLang/julia/issues/25930. The extensive explanations are wonderful if you use Jupyter or Juno, but they sometimes get in the way when you're wanting to do something quick at the REPL.

timholy commented 4 years ago

https://github.com/JuliaLang/julia/pull/34226