Documentation for Internal Functions

[mattBrzezinski]

Documentation is nice to define inputs/outputs and what a function does. Extending this out to internal functions would be nice as well, especially when coming back to revise the function. However, I don't think it's necessary to outline a full docstr for these internal functions.

Any thoughts on this? Suggestions for a format? Maybe something like,

function _foobar(x, y; z)
    """
    Explanation of what foobar does, maybe explain why it does things in a certain way?
    Have docstr inside the function for quick glance value that a function is internal?
    """
end

[mattBrzezinski]

cc: @fchorney I feel like you have thoughts around docstrs

[fchorney]

I just think julia docstrings in general are a little too verbose, but as far as this specific thing is considered, I'm honestly fine with defining proper docstrings for internal functions. I'm fine with just comments as well as it doesn't necessarily need a full API style docstring.

I guess I don't really have a strong preference on which style, but I think having docstrings of some sort even for internal functions is fine.

[oxinabox]

Docstrings for internal functions should still be outside the function. That way ? can be used with them. And you can generate a docs page for the internals. ChainRulesCore and TimeZones.jl both have such pages in their docs.

I would say that they are optional, and don't have to follow the format. Including can be written on 1 line. And that

"Fixes the thing"
function fix_thing()
...
end

Should be preferred over

#Fixes the thing
function fix_thing()
...
end