Define K_DOXYGEN as macro to check if kapidox/doxygen is run
Needs ReviewPublic

Authored by kossebau on Sun, Jan 12, 10:40 AM.

Details

Reviewers
None
Group Reviewers
Frameworks
Summary

Currently kapidox uses the macro DOXYGEN_SHOULD_SKIP_THIS to enable code
it processes to control what doxygen sees. That macro, while taken from
the example given in the official doxygen documentation,
( http://www.doxygen.nl/manual/faq.html#faq_code ) has some disadvantages:

  • it is not a macro officially set by doxygen
  • its semantic can be confusing to human readers in case it needs to be used with #ifdef instead of the #ifndef as in the doxygen documentation example

Example:
#ifdef DOXYGEN_SHOULD_SKIP_THIS
// will this code be processed by kapidox/doxygen? Yes, it will
#endif

Using a K_DOXYGEN macro definition instead follows an existing pattern
known from code checking the (compiler) tool being processed by, like
GNUC, clang or Q_QDOC.

Diff Detail

Repository
R264 KApiDox
Branch
introduceK_DOXYGEN
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 20997
Build 21015: arc lint + arc unit
kossebau created this revision.Sun, Jan 12, 10:40 AM
Restricted Application added projects: Frameworks, Documentation. · View Herald TranscriptSun, Jan 12, 10:40 AM
Restricted Application added subscribers: kde-doc-english, kde-frameworks-devel. · View Herald Transcript
kossebau requested review of this revision.Sun, Jan 12, 10:40 AM

Some similar macro definitions used by other projects, as I found by doing some random grepping over my system includes:

  • __GTK_DOC_IGNORE__
  • Q_QDOC & Q_CLANG_QDOC
  • DO_NOT_DOCUMENT
  • EIGEN_PARSED_BY_DOXYGEN
  • DOXYGEN
  • U_IN_DOXYGEN
  • BOOST_DOXYGEN_INVOKED & lots of similar
  • CV_DOXYGEN
  • DOXYGEN_ENABLED

So seems there is no real standard sadly. Going for a K_ prefix as namespace should also avoid any conflicts with potential definitions pulled in from others.

If this is in, I would then also adapt all KF code as well as ECMADDQCH.

No one any opinion? Guess most people have not run into the need to do pre-processor switches for the doc generation, and also never seen DOXYGEN_SHOULD_SKIP_THIS before.

So would move forward with this on Thursday, 23rd January, if no-one objects until then.