Best practice to document non-API functions

David_Sagan · December 25, 2023, 5:18am

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.

jules · December 25, 2023, 8:02am

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 https://github.com/JuliaLang/julia/pull/50105. Right now, I think you could just add a note that something is internal to its docstring.

David_Sagan · December 26, 2023, 6:38am

Very interesting. Thanks for the info.

sylvaticus · December 26, 2023, 9:09am

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

github.com

JuliaLang/julia/blob/master/NEWS.md

Julia v1.11 Release Notes
========================

New language features
---------------------
* `public` is a new keyword. Symbols marked with `public` are considered public
  API. Symbols marked with `export` are now also treated as public API. The
  difference between `public` and `export` is that `public` names do not become
  available when `using` a package/module ([#50105]).
* `ScopedValue` implement dynamic scope with inheritance across tasks ([#50958]).
* The new macro `Base.Cartesian.@ncallkw` is analogous to `Base.Cartesian.@ncall`,
  but allows to add keyword arguments to the function call ([#51501]).
* Support for Unicode 15.1 ([#51799]).
* A new `AbstractString` type, `AnnotatedString`, is introduced that allows for
  regional annotations to be attached to an underlying string. This type is
  particularly useful for holding styling information, and is used extensively
  in the new `StyledStrings` standard library. There is also a new `AnnotatedChar`
  type, that is the equivalent new `AbstractChar` type.
* `Manifest.toml` files can now be renamed in the format `Manifest-v{major}.{minor}.toml`
  to be preferentially picked up by the given julia version. i.e. in the same folder,

This file has been truncated. show original

lmiq · December 26, 2023, 9:21am

I use this: Documentation of internals

As a workaround.

jishnub · December 26, 2023, 11:59am

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.