On Thu, Jun 29, 2017 at 11:14 AM, Robert Dailey <rcdailey.li...@gmail.com> wrote:
> Doxygen supports linking external documentation together: > https://www.stack.nl/~dimitri/doxygen/manual/external.html > > Using doxygen_add_docs(), it doesn't provide built-in support for tag > files. I'm thinking this would be beneficial since the way the > function is designed encourages modular documentation. At least, I > have my projects structured like this (targets): > > A > A_doxygen > B > B_doxygen > C > C_doxygen > > I have 1 doxygen target per real library target. And each library has > dependencies on others. When library C uses something from A, I want > C_doxygen to link to the tagfile generated by A_doxygen. > > At the moment I'm accomplishing this by adding a target property to > each real target to keep track of target dependencies. Example: > > add_library(C ...) > target_link_libraries(C A) > set_property(TARGET C PROPERTY TARGET_DEPENDENCIES A) > > When I'm building A_doxygen target (using doxygen_add_docs()), I > specify DOXYGEN_GENERATE_TAGFILE. Then in C_doxygen, I specify > DOXYGEN_TAGFILES to point to the one output by A_doxygen. > > I don't like keeping target properties to query the dependency tree, > but this is the best I could come up with. Is there value in > incorporating this into FindDoxygen.cmake? If so, I'd like to > contribute it, if it's useful. > I think there's good potential for this idea. The doxygen_add_docs() function could record the value of the DOXYGEN_GENERATE_TAGFILE variable in a target property (I'd recommend using the same name as the variable). A new DEPENDS option could be added to doxygen_add_docs() which would specify other targets this one depends on. This would invoke add_dependencies() to fulfil build ordering as usual, but it could also inspect the target properties of the dependees and if the DOXYGEN_GENERATE_TAGFILE property is set, then the DOXYGEN_TAGFILES variable could be augmented to pick up that tag file somehow. You'd have to be careful how the paths were handled to ensure they worked robustly, but conceptually at least I think this might be possible and useful. Example usage would then be something like this: # Populate DOXYGEN_GENERATE_TAGFILE if not already set, # use existing contents otherwise. Either way, define a target property # on foo which records the value. doxygen_add_docs(foo) # Does a similar thing as above for this target, but also picks up the # tag file from foo as recorded in its target properties and augments # the DOXYGEN_TAGFILES variable as appropriate. doxygen_add_docs(bar DEPENDS foo) You would need to be careful with how to handle contents of DOXYGEN_GENERATE_TAGFILE and DOXYGEN_TAGFILES that the project might already set. As a conservative measure, you might want to consider adding an option NO_AUTO_TAGFILES or similar to disable any of this logic in case a project does something complex and doxygen_add_docs() needs to be told to leave it completely up to the project to handle. The doxygen_add_docs() function was originally added with the intention of making it as easy as possible for projects to use Doxygen with minimal extra configuration, so I think having the auto tag handling enabled by default would probably be the right call, as long as there's a way for projects to disable it if needed. -- Craig Scott Melbourne, Australia https://crascit.com
-- Powered by www.kitware.com Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Kitware offers various services to support the CMake community. For more information on each offering, please visit: CMake Support: http://cmake.org/cmake/help/support.html CMake Consulting: http://cmake.org/cmake/help/consulting.html CMake Training Courses: http://cmake.org/cmake/help/training.html Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Follow this link to subscribe/unsubscribe: http://public.kitware.com/mailman/listinfo/cmake-developers
