On Tue, Nov 12, 2019 at 6:57 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > Heba Waly <heba.waly@xxxxxxxxx> writes: > > > So my proposal for this matter is to investigate the possibility of > > using a doc generators that'd extract the documentations from the code > > to a single doc file per library. > > Something like that may become necessary to bring docs in some of > the *.h files up to par with D/t/api-*.txt. > > Note that the quality of the latter is quite uneven. The one I > noticed perhaps is exceptionally well-structured (even if some of > the details of its contents may have gotten stale) and to match its > structure, the order of presentation in the generated doc may have > to be different from the order of definitions in the header. > > But for the ones with poor structure with stale contents, getting > rid of the stale D/t/api-*.txt and describing the API in *.h files > is a vast improvement. I agree. Back to the main issue you raised in the beginning: lets look at two different scenarios before and after moving the docs, the first scenario is the one you've been through trying to look for PARSE_OPT_STOP_AT_NON_OPTION, luckily you found it in Documentation/technical/api-parse-options.txt and the doc was pretty useful for you. But if you were looking for PARSE_OPT_ONE_SHOT instead, which is not documented in the doc file, you'd have ended up in parse-options.h with no documentation, even searching for the enum parse_opt_flags itself won't lead to anything useful I assume. On the other hand, after moving the docs to the header file in the last version of this patch, if we're trying to look for either PARSE_OPT_STOP_AT_NON_OPTION or PARSE_OPT_ONE_SHOT, we'll find that it's a member of parse_opt_flags, searching for the enum will lead us to the explanation paragraph in the top of the header file (which was moved from the D/t/api-parse-options.txt) which I think sounds convenient enough as it's in the same file, and didn't go through much trouble to find the needed info. Happy to discuss more suggestions though. Thanks, Heba
