Improve some docstrings

[natema]

WorldDynamics.jl/src/functions.jl

Line 9 in 1ea057e

Returns the value of a function with input `x`, by linearly interpolating the function itself through the table `yvalues` and the range `xrange`. If `x` is out of the range, the value at the corresponding extremity is returned. This function corresponds to the `TABHL` function in the `DYNAMO` language. This latter function receives a table (that is, `yvalues`), a value (that is, `x`), a left and a right extreme of an interval (that is, `xrange`), and an increment value.

• What about enforcing one-line-per-sentence in docstrings?
• The definition of interpolate is unclear and can be improved, in particular when we say by linearly interpolating the function itself through the table.
• The docstring of the Interpolate single value is missing.

[paulobruno]

What about enforcing one-line-per-sentence in docstrings?

The common approach is to enforce at most 80 characters. I'm fine with 80 chars.

The docstring of the Interpolate single value is missing

Do we need it? It's no supposed to be public.
Maybe adding an underscore to follow the common "private" functions pattern. What do you think?

[natema]

I agree with underscore with no docstrings.
I'm also fine with the 80 char limit if that's more common, even though one-sentence-per-line should be easier to diff.

[paulobruno]

Yes, one sentence per line is better to diff, which is very useful for text files, like readme and latex.

[natema]

Does it mean you agree with adopting that convention in docstrings?

[paulobruno]

The case of code and docstrings is that some things, like old terminal versions and Julia documentation renderer, trim the text.
In this case, we should go for the 80 chars limitation.

[natema]

Julia doesn't trim the text.
I don't know what terminals still used today do.

[natema]

Ah sorry I read it too fast, you mean code blocks displayed in the documentation pages... right.