Documentation of internals

Having the ? keyword to access documentation is very practical, but that exposes the documentation to the user, thus it may be risky for internal functions not having a stable interface. Because of that, I was modifying my help entries to something like:


ranges_of_replicas(cell_size, lcell, nc, unit_cell_matrix::SMatrix{3,3,T}) where T

Internal function or structure - interface may change.

# Extended help

Function that sets which is the range of periodic images necessary to fill
the computing box, in 3D.

In such a way that ? exposed the “Internal function warning” and the extended help is still available.

I like that solution, but at one point I thougth that someone may have already thought of this and provided a package/solution which is more general and used. For instance, a macro that does something similar to the above for docs marked as “internals”.

Anything like that in the ecosystem already? Or other more standard ways of dealing with this?

As a parallel thing, it would be nice if Documenter could handle two classes of help entries - one for the exposed API and other for these “internals”, to be rendered to different pages or sections of the docs.

2 Likes