On 04.01.2019 15:48, Daniel Shahaf wrote: > Branko Čibej wrote on Fri, 04 Jan 2019 15:42 +0100: >> On 04.01.2019 15:35, Daniel Shahaf wrote: >>> Branko Čibej wrote on Fri, 04 Jan 2019 15:31 +0100: >>>> On 04.01.2019 15:20, Daniel Shahaf wrote: >>>>> br...@apache.org wrote on Fri, 04 Jan 2019 10:38 +0000: >>>>>> Move (some of the) standalone types into separate implementation headers >>>>>> so that SVN++ can use them directly without exposing APR or other >>>>>> dependencies. >>>>>> +++ subversion/trunk/subversion/include/svn_opt_impl.h Fri Jan 4 >>>>>> 10:38:53 2019 >>>>>> @@ -0,0 +1,83 @@ >>>>>> + * @file svn_opt.h >>>>>> + * @brief Option and argument parsing for Subversion command lines >>>>>> + * (common implementation) >>>>>> + */ >>>>>> + >>>>>> +/* NOTE: >>>>>> + * This file *must not* include or depend on any other header except >>>>>> + * the C standard library headers. >>>>>> + */ >>>>> Could the comment also explain the rationale for the restriction it >>>>> imposes? >>>> No, not in every "impl" header we happen to create. But it is documented >>>> in subversion/bindings/cxx/README, as one of the SVN++ design goals. >>> Shouldn't this be documented in the C API's documentation too, at least >>> by reference? Someone working on the C headers in a year or three might >>> not think to look in the C++ bindings for design choices of the C API. >> If you have an idea how to do that without boring repetition, please go >> ahead. > We could add a paragraph to HACKING, or possibly to a single global > doxygen file, explaining the _impl.h convention, rather than repeating > the explanation in each individual file.
A Doxygen file wouldn't work since we don't use generated docs for developer guidelines, but a paragraph in HACKING about C++ bindings and similar policy would work. -- Brane
