Project

General

Profile

Feature #2139

More precise/explicit documentation conventions

Added by Eric Irrgang over 2 years ago. Updated almost 2 years ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
documentation
Target version:
-
Difficulty:
uncategorized
Close

Description

When viewing the "library" or "full" documentation generated by doxygen, it is hard to tell whether the documentation under inspection refers to an entity that is part of the public API or would be visible under a less detailed version of the docs. Some provision for this difficulty is made by including the groups group_publicapi or group_libraryapi to appear as links at the top of the page, but not all entities can be part of multiple groups and no group explicitly exists for group_implementation_detail or some such thing.

Similarly, there is no section name for the default section (not libapi or internal), which is usual for doxygen but requires that someone browsing the source code be acutely aware of the doxygen scoping rules.

Question 1: Would it be useful to have a group name that distinguishes non-API code and/or a section name for public API?

Question 2: Instead, what about adding a doxygen "tag" or badge to indicate the API level of an entity, the way protection levels of code is automatically called out? I don't know how hard that is...

Question 3: The doxygen distinctions of "section" and "group" are blurry since they are both used to affect the visibility of code in different contexts while browsing documentation. Would it be reasonable to adopt stricter vocabulary in the developer guide and internal comments? I.e. "Flavor," "level," and "section" are all used in the documentation guide but mean the same thing, as well as "variant" used internally.

Associated revisions

Revision 91ea2482 (diff)
Added by Paul Bauer about 2 months ago

Removes checker for installed files

As the plan is to remove the current handling of installed header files,
this removes the checker parts from the doxygen check-source script for
this attribute.

Refs #2382, #2139, #988

Change-Id: I76b519f39a5c793c9f1ea8c1eb5eebb39b4a9352

Revision 52e3d670 (diff)
Added by Paul Bauer about 2 months ago

Remove installed headers from CMake

Removed the gmx_install_header sections from CMake files, as well as the
CMake code used to add and check them.

Refs #2382, #2139, #988

Change-Id: I4525ea14d2967f83d940300daeb2ade08717ed5d

History

#1 Updated by Teemu Murtola over 2 years ago

  • Category set to documentation

"section" is used in all of doxygen.rst only to refer to 1) sections of text in the documentation (the rst files), and 2) to refer to the values used with doxygen ENABLED_SECTIONS, so I do not understand many of your comments about ambiguity or question 3.

Why would you want to have a separate publicapi section in this sense? If it had the same semantics as libapi, it would be always true and would not provide any additional value. And \ifnot libapi already covers the other possible use case, although I'm not sure how useful that would be in general.

A separate group for internal could make sense, but would require a lot of redundant declarations everywhere, so I'm not sure whether it would be worth the effort.

There are no "badges" or anything in doxygen. Using a home-bred Python script to patch the HTML output could work with some significant effort, but can tie us even more tightly to a particular Doxygen version. Perhaps the best way would be to invest in a custom script to autogenerate the module pages (removing the need to have \ingroup module_abc anywhere). This would be some work, but would allow using the public/library API groups everywhere. And it would reduce the need to manually maintain the module memberships.

#2 Updated by Eric Irrgang almost 2 years ago

Teemu Murtola wrote:

"section" is used in all of doxygen.rst only to refer to 1) sections of text in the documentation (the rst files), and 2) to refer to the values used with doxygen ENABLED_SECTIONS, so I do not understand many of your comments about ambiguity or question 3.

Yes, I think use of the word "section" in doxygen.rst is consistent and unambiguous, but when cross-referencing that document with style encountered in the source code, the semantics of "flavor", "level", and "variant" are less clear.

Why would you want to have a separate publicapi section in this sense? If it had the same semantics as libapi, it would be always true and would not provide any additional value. And \ifnot libapi already covers the other possible use case, although I'm not sure how useful that would be in general.

Wouldn't \ifnot libapi also match \if internal? I don't know if a publicapi section would make sense, particularly if it were effectively inclusive of libapi. I'm trying to think of a reasonable way to include additional annotation in source files to remind someone whether they are looking at code that is documented in the default (public) section versus code that does not appear in the online docs at all. It seems in a lot of cases that the public API is inferred through doxygen visibility rather than explicit annotation, particularly since public, library, and internal documentation often appear in the same source files. This isn't particularly confusing if you are only looking at the rendered public API documentation, but a newcomer looking at either rendered library documentation or source code can easily miss the distinction in API level.

A separate group for internal could make sense, but would require a lot of redundant declarations everywhere, so I'm not sure whether it would be worth the effort.

It probably isn't worth the effort and it might be better solved in other ways. Namespaces and distinct header files can improve source code viewing, but I don't know if that is sufficient for clarification in doxygen. Maybe the subgrouping would be helpful with ``name ... { @}``

There are no "badges" or anything in doxygen. Using a home-bred Python script to patch the HTML output could work with some significant effort, but can tie us even more tightly to a particular Doxygen version. Perhaps the best way would be to invest in a custom script to autogenerate the module pages (removing the need to have \ingroup module_abc anywhere). This would be some work, but would allow using the public/library API groups everywhere. And it would reduce the need to manually maintain the module memberships.

I would be afraid that additional GROMACS-specific infrastructure is more likely to hurt readability instead of to help it for the newcomer readers I'm thinking of. For one thing, it would be less Google-able than doxygen conventions. But the definitions of modules, groups, and directories is already a bit obscure, so maybe you're onto something. I suppose the gist of my issue is that a module can have documentation for public API, library API, and implementation details / internal API, and readability would be helped by clearer distinction in both the html output and within the code. This may be more of a structural issue than a technological (doxygen) issue.

Also available in: Atom PDF