refeactor and docs

[rafaqz]

What the pull request does
Refactors and cleans up a little, standardises all algorithm arguments and docs, and fixes documentation so there are no warnings - which means documenting everything exported, and moving a lot of docs to code comments.

Type of change
Please indicate the relevant option(s)

• [ ] :bug: Bug fix (non-breaking change which fixes an issue)
• [ ] :sparkle: New feature (non-breaking change which adds functionality)
• [ ] :boom: Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [x] :book: This change requires a documentation update

Checklist

• [ ] The changes are documented
  • [ ] The docstrings of the different functions describe the arguments, purpose, and behavior
  • [ ] There are examples in the documentation website
• [ ] The changes are tested
• [x] The changes do not modify the behavior of the previously existing functions
  • If they do, please explain why and how in the introduction paragraph
• [ ] For new contributors - my name and information are added to .zenodo.json
• [ ] The Project.toml field version has been updated
  • Change the last number for a v0.0.x series release, a bug fix, or a performance improvement
  • Change the middle number for additional features that do not break the current test suite (unless you fix a bug in the test suite)
  • Change the first number for changes that break the current test suite

[codecov-io]

Codecov Report

Merging #49 (cecab92) into main (18df1db) will decrease coverage by 0.74%. The diff coverage is 50.00%.

@@            Coverage Diff             @@
##             main      #49      +/-   ##
==========================================
- Coverage   62.45%   61.71%   -0.75%     
==========================================
  Files          14       14              
  Lines         277      269       -8     
==========================================
- Hits          173      166       -7     
+ Misses        104      103       -1     

Flag	Coverage Δ
unittests	61.71% <50.00%> (-0.75%)	:arrow_down:

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
src/NeutralLandscapes.jl	100.00% <ø> (ø)
src/algorithms/discretevoronoi.jl	0.00% <0.00%> (ø)
src/algorithms/distancegradient.jl	0.00% <ø> (ø)
src/algorithms/edgegradient.jl	100.00% <ø> (ø)
src/algorithms/nncluster.jl	0.00% <0.00%> (ø)
src/algorithms/nnelement.jl	94.44% <ø> (-0.30%)	:arrow_down:
src/algorithms/nogradient.jl	100.00% <ø> (ø)
src/algorithms/perlinnoise.jl	89.65% <ø> (ø)
src/algorithms/planargradient.jl	100.00% <ø> (ø)
src/algorithms/rectangularcluster.jl	100.00% <ø> (ø)
... and 5 more

---

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 18df1db...cecab92. Read the comment docs.

[mkborregaard]

But why do we want docstrings on unexported functions that are never meant to be user-facing?

[tpoisot]

But why do we want docstrings on unexported functions that are never meant to be user-facing?

Maybe that's just me, but I like having the docstring when I'm writing things for the package - as in, when I hover the function name in VS Code - it's easier than having to look into the code for the comments.

[mkborregaard]

It seems a little strange to me, but I don't feel strongly about it, as long as they are kept out of the docs :-)

[rafaqz]

If you have docstrings not in the docs, you get a warning so tests wont pass when strict=true. If you turn off strict to fix this, they will pass when a new PR misses a docstring or messes something up.

The idea was to enforce documentation. Its made my life a lot easier on my own packages to get test failures whenever the docs break in any way, and made the docs more reliable.

Otherwise Im easy either way. But underscore functions are for devs only, so comments seem right to me anyway?

And why not use @kwdef? I guess we can write the constructors out. But it is a base macro.

[tpoisot]

Let's use @kwdef if it makes it user frieldier. I still think internal functions should be documented - a thing that many packages do is to have a specific page for them called "internals" or something. It can start with a disclaimer that people should probably not use these functions for daily use.

[mkborregaard]

I'm OK with having them under "internals" if that is useful for you guys. And I don't care either way about kwdef :-) Then we just have some docstrings to write - I didn't docstring any internal functions.

[tpoisot]

I'm fine with the package as is, so I'm going to merge and tag as soon as it passes. I'll start building the SimpleSDMLayers integration as soon as we have a version!