Best practice to document non-API functions

I am developing a rather large package that will have a substantial number of functions that are low level and not part of the API. I am new to Julia and am not sure the best way of documenting these. I could write doc strings for them but I have a concern that that would “pollute” the help system in terms a “user” trying to learn about the functions that are in the API. Is this a valid concern? The alternative is to put comments in the file where the doc strings would go. But then I’m concerned about someone helping with coding of the package who might want to use the help system for the non-API functions.

Any guidance is greatly appreciated.


That a docstring means that a nonexported function is public api is only a heuristic, and not a good one in my opinion. Developer docs are valuable and, as you say, you may want to discover these through the repl just like the normal docs.

In future versions of julia, the new public keyword will help to discriminate between internal and public nonexported functions Right now, I think you could just add a note that something is internal to its docstring.


Very interesting. Thanks for the info.

Specifically, should be in julia v1.11, around half year from now…

1 Like

I use this: Documentation of internals

As a workaround.

Worth noting that Julia doesn’t follow the convention that all methods with docstrings are public. In Julia Base, only the types/methods that are explicitly included in the documentation are public. Internal types and methods may have docstrings, but just because a docstring exists doesn’t imply that the name is public. Version v1.11 of Julia would make this more explicit, with a warning about bindings being internal.

1 Like