[CMake] Announcing CMake BASIS, a set of CMake based project interoperability and automation tools

[Matthew Woehlke]

On 2014-01-28 01:11, Andrew Hundt wrote:
> On Mon, Jan 27, 2014 at 3:30 PM, Matthew Woehlke wrote:
>> I didn't look at it yet, but to be "optimally" useful I would hope that an
>> implementation of generating doxygen documentation would:
>
> What we have won't be "optimally" useful, but it is "very" useful. I think
> if it is integrated the additional steps to reach "optimal" usefulness
> could be added over time.

What's important is to not design the interface in a way that precludes 
adding features that are known/expected to be wanted :-). If you can 
avoid that trap, then there is no problem adding features incrementally.

>> - implement two-step generation of tag files followed by the actual
>> documentation
>>
>> - allow the user to provide a list of library names to be used as input
>> tag files (assuming those targets use the same mechanism to generate
>> documentation)
>>
>> - implement the above in a manner that allows the user some mechanism to
>> define 'custom' targets with their own tag file(s) for external
>> documentation
>>
>> - allow for circular linking (this is why tags and doc need to be separate
>> steps; the tags have no dependencies, but the docs depend on the referenced
>> tags; splitting the two avoids creating dependency cycles)
>
> These steps seem like a fairly complicated and specialized use case rather
> than a typical one. Perhaps I am mistaken?

The ability to declare "virtual" dependencies is probably not unusual 
(I'd be surprised if there aren't at least a fair number of projects 
that would like to be able to link their own doc to Qt's doc, for 
example). Requiring an extra tag file for Qt is a bit unusual, though 
given the deficiencies in Qt's tag file (e.g. did you know it doesn't 
provide links for enum values?) I could imagine that is more because no 
one else has made the effort to extract the missing tags.

Having circular tag dependencies is probably "somewhat" unusual.

FWIW, the above is basically a description of the features of the 
'generate doxygen documentation' implementation that tends to get copied 
around projects I'm working on.

>> In particular, I have a project where I want to be able to link to Qt
>> documentation, but due to deficiencies in how Qt generates its tag file, I
>> actually need to generate my own supplementary tag file. I want to be able
>> to use this just by listing "Qt" as a documentation dependency.
>
> The current version of the doxygen component wraps the support provided in
> a normal doxyfile and also provides several filters which allow a few extra
> languages to be documented, including the CMake language itself.

That's clever. (Although with CMake 3.0 it would be better for CMake 
stuff to extract CMake's sphinx documentation system into a separate 
project and use that, as reST has become the preferred standard for 
CMake documentation.)

> Here is the full documentation of the doxygen component
> <http://opensource.andreasschuh.com/cmake-basis/apidoc/latest/DocTools_8cmake.html#a6a37a66eb28f7969ef27b004f8faaa3a>

The main thing I don't see is tag file support. In any multi-library 
project that doesn't generate monolithic documentation, tag file support 
is not an optional feature.

For my use, tag file support via target dependencies is pretty much a 
"must have".

I would also encourage you to consider what parameters are likely to be 
set project-wide and provide for them to default to a well-known 
variable (i.e. that could be set in the root CMakeLists.txt). For 
example, DOXYFILE, OUTPUT, HTML_EXTRA_STYLESHEET...

-- 
Matthew