[CMake] general question on documenting modules using the new FooConfig.cmake files

[Alexander Neundorf]

Hi,

I've got a general question.
Regular cmake FindFoo.cmake modules are documented by putting the docs at the 
top of the file.
This documentation should list the variables, macros etc. provided by that 
module.

Now if I switch to using FooConfig.cmake files and just very simple 
FindFoo.cmake files (basically only for getting some nicer messages etc.), 
how do I do this then ?
I still could put the documentation in the FindFoo.cmake file, but this 
documentation would be for stuff which is in the FooConfig.cmake file, which 
is loaded later.
While this is no technical problem, there is the real problem that the 
contents of the FooConfig.cmake file can change, i.e. a new variable can be 
added. But this doesn't necessarily mean that also the FindFoo.cmake changes. 
But if it doesn't, then the documentation is out of date.

So, what would you prefer where to put the documentation ?
In the FooConfig.cmake file, which is relatively hidden ?
Or in the FindFoo.cmake file, which can get out of sync to the contents of the 
FooConfig.cmake file ?

Alex