[cmake-developers] Built-in tag support for FindDoxygen

[Robert Dailey]

I ran into an interesting situation. Originally, I had based
documentation on real targets. And in some ways, I still do, but not
directly anymore. I have some targets that are conditionally only
built on certain platforms. However, I wanted documentation for that
target to be generated regardless of platform. That means I cannot
bind a doxygen target to its real target, since it may not be there.
Everything else functions the same, and doxygen targets still build a
"mirror" of the dependency tree of the real targets amongst
themselves. Also the tag file generation happens the same way.

What I'd like to do is maybe put my doxygen CMake code (that simply
wraps doxygen_add_docs()) on a Gist for now or something, along with
some usage examples, and see what you think as far as implementation
goes. From there we can decide what needs to be integrated, or if
maybe this is a separate function provided by FindDoxygen.cmake.

I'll follow up later. Thanks for your advice.

On Fri, Jun 30, 2017 at 9:48 PM, Craig Scott <craig.scott at crascit.com> wrote:
>
>
> On Thu, Jun 29, 2017 at 11:14 AM, Robert Dailey <rcdailey.lists at 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