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
--
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://www.cmake.org/mailman/listinfo/cmake
