currently the developers page at the OF website says:
If the package contains functions which for some reason should not
be advertised, they can be listed under the category ‘Internal’ in
the INDEX file. In the future, this category will be handled
specially in generating the online documentation.
I'm not sure anymore about the last sentence. Arguments (Julien) for
such non-private but not advertised functions were:
- experimental functions,
- helper functions which may also be directly used, but normally are
not.
But treating a category 'Internal' in a special way would mean some
complications to the code of generate_html and of the website. And the
only thing we could achieve by this would be not exposing the helptext
of such functions (the function name must still be listed to enable
checking for defined symbols).
Is this really worth the effort? Would it not be equivalent, or even
better, to expose the help text, but to state the special status of
the function in it -- i.e. 'This function should be considered
experimental ... (help text follows)' or 'undocumented internal
function' (with help only as a comment in the source)?