From: Vladimír Vondruš Date: Mon, 12 Apr 2021 13:47:04 +0000 (+0200) Subject: doc: clarify naming for such an important option. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=3a294739e2d351a40b94527eabd7c228d17b56be;p=blog.git doc: clarify naming for such an important option. Even I don't remember how it's meant to be named anymore, sigh. --- diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst index a3e1a64a..22cc947e 100644 --- a/doc/documentation/doxygen.rst +++ b/doc/documentation/doxygen.rst @@ -163,7 +163,8 @@ In addition to features `shared by all doc generators <{filename}/documentation. documentation practices --- having the output consist of an actual human-written documentation instead of just autogenerated lists. If you *really* want to have them included in the output, you can enable them - using a default-to-off :ini:`SHOW_UNDOCUMENTED` option, but there are some + using a default-to-off :py:`SHOW_UNDOCUMENTED` option in ``conf.py`` (or + :ini:`M_SHOW_UNDOCUMENTED` in the ``Doxyfile``), but there are some tradeoffs. See `Showing undocumented symbols and files`_ for more information. - Table of contents is generated for compound references as well, containing @@ -715,7 +716,8 @@ shown. In some cases, however, it might be desirable to show undocumented symbols as well --- for example when converting an existing project from vanilla Doxygen to m.css, not all APIs might be documented yet and thus the output would be -incomplete. The :py:`SHOW_UNDOCUMENTED` option unconditionally makes all +incomplete. The :py:`SHOW_UNDOCUMENTED` option in ``conf.py`` (or +:ini:`M_SHOW_UNDOCUMENTED` in the ``Doxyfile``) unconditionally makes all undocumented symbols, files and directories "appear documented". Note, however, that Doxygen itself doesn't allow to link to undocumented symbols and so even though the undocumented symbols are present in the output, nothing is able to