On 2014-01-08 12:57, Brad King wrote:
On 01/08/2014 12:00 PM, Matthew Woehlke wrote:
Since you mentioned it, I was wondering if this is related to a feature
I was asking about, but I don't understand how it works; it seems to
only ever generate a short boilerplate text.
Is this meant to take a CMake module that is not part of the CMake
distribution and extract and format the documentation from the same?
The old documentation system exposed this feature through the old
--help-custom-modules option. The new documentation system does not.
This commit is about making old builds not totally break.
Because that is a feature I really wish CMake 3.0 would provide. (I know
you (Brad) previously mentioned that you don't want to in order to avoid
committing to any sort of compatibility guarantees with respect to the
same. But it still seems to me that such decision makes it unnecessarily
hard for third parties to provide documented CMake modules.)
Anyone could fork CMake's Utilities/Sphinx infrastructure and provide
it as a separate distribution with support and compatibility guarantees.
I just do not want to provide it with CMake and constrain CMake's own
documentation from evolving just to support external documents. The
compatibility issue in this thread is a perfect example of why.
From my perspective, that's sort-of the point here... CMake used to
provide for generating documentation from external modules. Now it
doesn't. And it seems that KDE is also feeling that pain.
I'm not convinced that's a good thing. I get that you don't want to make
things harder for developers, but doing so at the expense of making
things harder for users doesn't seem like the best trade-off.
I'm also not sure I'm convinced by the compatibility argument. If you
can't guarantee compatibility, then don't. Projects that want to use
CMake to generate documentation for their CMake modules simply must use
the version of CMake their documentation was written for to do so. (And
update as necessary to meet the previous condition. Or fork the
documentation system anyway.)
--
Matthew
--
Powered by www.kitware.com
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
