D26602: Define K_DOXYGEN as macro to check if kapidox/doxygen is run
kossebau created this revision. kossebau added a reviewer: Frameworks. Herald added projects: Frameworks, Documentation. Herald added subscribers: kde-doc-english, kde-frameworks-devel. kossebau requested review of this revision. REVISION 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. REPOSITORY R264 KApiDox BRANCH introduceK_DOXYGEN REVISION DETAIL https://phabricator.kde.org/D26602 AFFECTED FILES README.md src/kapidox/data/Doxyfile.global To: kossebau, #frameworks Cc: kde-frameworks-devel, kde-doc-english, LeGast00n, gennad, fbampaloukas, GB_2, michaelh, ngraham, bruns, skadinna
D26602: Define K_DOXYGEN as macro to check if kapidox/doxygen is run
kossebau added a comment. 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. REPOSITORY R264 KApiDox REVISION DETAIL https://phabricator.kde.org/D26602 To: kossebau, #frameworks Cc: kde-frameworks-devel, kde-doc-english, LeGast00n, gennad, fbampaloukas, GB_2, michaelh, ngraham, bruns, skadinna
D26602: Define K_DOXYGEN as macro to check if kapidox/doxygen is run
kossebau added a comment. 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. REPOSITORY R264 KApiDox REVISION DETAIL https://phabricator.kde.org/D26602 To: kossebau, #frameworks Cc: kde-frameworks-devel, kde-doc-english, LeGast00n, gennad, fbampaloukas, GB_2, michaelh, ngraham, bruns, skadinna
D26602: Define K_DOXYGEN as macro to check if kapidox/doxygen is run
This revision was not accepted when it landed; it landed in state "Needs Review". This revision was automatically updated to reflect the committed changes. Closed by commit R264:c4a632ab65da: Define K_DOXYGEN as macro to check if kapidox/doxygen is run (authored by kossebau). CHANGED PRIOR TO COMMIT https://phabricator.kde.org/D26602?vs=73330&id=74211#toc REPOSITORY R264 KApiDox CHANGES SINCE LAST UPDATE https://phabricator.kde.org/D26602?vs=73330&id=74211 REVISION DETAIL https://phabricator.kde.org/D26602 AFFECTED FILES README.md src/kapidox/data/Doxyfile.global To: kossebau, #frameworks Cc: kde-frameworks-devel, kde-doc-english, LeGast00n, gennad, fbampaloukas, GB_2, michaelh, ngraham, bruns, skadinna
