While adding a .clang-format file to WIL, I noticed a couple issues that needed to be sorted out manually:
Some tests are dependent on formatting; specifically those that use __LINE__
Some code greatly benefits from disabling auto-formatting
clang-format seems to wrap lines that use Doxygen \command syntax aggressively and incorrectly while it does not seem to wrap lines that use @command syntax at all
For the first two, I've added several //clang-format off and //clang-format on comment pairs where necessary.
For the last, I've converted everything to @command syntax and I've manually wrapped lines that contain Doxygen style comments (begins with ///, //!, /**, or /*!). Note that I've wrapped at either 130 columns or 134 columns since the .clang-format file will wrap at 130 lines, but it will also reduce namespace indentation by one tab's worth.
I wanted to address these things separately because it's a lot easier to re-sync to master & re-run clang-format if I want to test something out (or sync new changes).
In order to validate the changes to the Doxygen comments, I've added a CMake target for generating the documentation (that's enabled only if you have Doxygen available in your PATH). E.g. run ninja docs to generate them.
I've also tried to fix up any issues I've seen with the Doxygen comments that I've seen. A few things to comment on:
Handling of ~~~ code snippets seems very hit or miss. It seems to have issues with snippets that contain comments, however I've not found that to be a hard rule - I believe I've seen examples that violate that in both ways
For some reason, Doxygen really likes to link things to com_ptr_t. This is especially true of anything that it cannot find definitions for: things like HSTRING, but also even things like void or typename(!). I cannot for the life of me figure these out
Doxygen seems to randomly stop processing some files. I first noticed this with resource.h, however I think(?) that resolved itself somehow, however I now see that issue with winrt.h. This seems correlated with the closing } of the wilnamespace. I.e. definitions in subsequent definitions of the namespace will not appear in the documentation. I also cannot for the life of me figure that out.
Some tokens appear to be handled incorrectly. E.g. I've come across something like _When_ appearing in the documentation as a function, even though it should be getting defined to nothing. I don't recall where I saw that or even if it's still happening.
The only remaining Doxygen warnings that aren't "thing is not documented" are:
G:/wil/include/wil/result_macros.h:2616: warning: unable to resolve reference to 'wil::g_fResultThrowPlatformException' for \ref command
G:/wil/include/wil/registry.h:2908: warning: argument 'key' from the argument list of wil::reg::get_value_expanded_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2908: warning: argument 'subkey' from the argument list of wil::reg::get_value_expanded_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2908: warning: argument 'value_name' from the argument list of wil::reg::get_value_expanded_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2908: warning: argument 'return_value' from the argument list of wil::reg::get_value_expanded_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2925: warning: argument 'key' from the argument list of wil::reg::get_value_expanded_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2925: warning: argument 'value_name' from the argument list of wil::reg::get_value_expanded_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2925: warning: argument 'return_value' from the argument list of wil::reg::get_value_expanded_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2603: warning: argument 'key' from the argument list of wil::reg::get_value_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2603: warning: argument 'subkey' from the argument list of wil::reg::get_value_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2603: warning: argument 'value_name' from the argument list of wil::reg::get_value_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2603: warning: argument 'return_value' from the argument list of wil::reg::get_value_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2620: warning: argument 'key' from the argument list of wil::reg::get_value_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2620: warning: argument 'value_name' from the argument list of wil::reg::get_value_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2620: warning: argument 'return_value' from the argument list of wil::reg::get_value_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2633: warning: argument 'key' from the argument list of wil::reg::get_value_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2633: warning: argument 'subkey' from the argument list of wil::reg::get_value_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2633: warning: argument 'value_name' from the argument list of wil::reg::get_value_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2633: warning: argument 'return_value' from the argument list of wil::reg::get_value_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2648: warning: argument 'key' from the argument list of wil::reg::get_value_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2648: warning: argument 'value_name' from the argument list of wil::reg::get_value_string_nothrow has multiple @param documentation sections
G:/wil/include/wil/registry.h:2648: warning: argument 'return_value' from the argument list of wil::reg::get_value_string_nothrow has multiple @param documentation sections
While adding a
.clang-formatfile to WIL, I noticed a couple issues that needed to be sorted out manually:__LINE__clang-formatseems to wrap lines that use Doxygen\commandsyntax aggressively and incorrectly while it does not seem to wrap lines that use@commandsyntax at allFor the first two, I've added several
//clang-format offand//clang-format oncomment pairs where necessary.For the last, I've converted everything to
@commandsyntax and I've manually wrapped lines that contain Doxygen style comments (begins with///,//!,/**, or/*!). Note that I've wrapped at either 130 columns or 134 columns since the.clang-formatfile will wrap at 130 lines, but it will also reduce namespace indentation by one tab's worth.I wanted to address these things separately because it's a lot easier to re-sync to master & re-run
clang-formatif I want to test something out (or sync new changes).In order to validate the changes to the Doxygen comments, I've added a CMake target for generating the documentation (that's enabled only if you have Doxygen available in your PATH). E.g. run
ninja docsto generate them.I've also tried to fix up any issues I've seen with the Doxygen comments that I've seen. A few things to comment on:
~~~code snippets seems very hit or miss. It seems to have issues with snippets that contain comments, however I've not found that to be a hard rule - I believe I've seen examples that violate that in both wayscom_ptr_t. This is especially true of anything that it cannot find definitions for: things likeHSTRING, but also even things likevoidortypename(!). I cannot for the life of me figure these outresource.h, however I think(?) that resolved itself somehow, however I now see that issue withwinrt.h. This seems correlated with the closing}of thewilnamespace. I.e. definitions in subsequent definitions of thenamespacewill not appear in the documentation. I also cannot for the life of me figure that out._When_appearing in the documentation as a function, even though it should be getting defined to nothing. I don't recall where I saw that or even if it's still happening.The only remaining Doxygen warnings that aren't "thing is not documented" are: