Re: [PATCH v2 15/20] parse-options: move doc to parse-options.h
- From
Heba Waly <heba.waly@gmail.com>
- Date
- Nov 15, 2019, 09:55 UTC
- Message-ID
- <CACg5j25ZO3+=EHYm5-Yp_LKEQA00EH=FAhOeP_TqHw8anCUDEg@mail.gmail.com>
- In-Reply-To
- <xmqqblthfxho.fsf@gitster-ct.c.googlers.com>
On Tue, Nov 12, 2019 at 6:57 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 19 quoted lines
> > Heba Waly <heba.waly@gmail.com> 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