Em Wed, 10 Aug 2016 10:46:44 +0300 Jani Nikula <jani.nikula@xxxxxxxxx> escreveu: > On Mon, 08 Aug 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote: > > The goal of Documentation/sphinx/parse-headers.pl script is to generate > > such parsed headers, with the cross-references modified by an exceptions > > file at Documentation/media/*.h.rst.exceptions. > > Would you be so kind as to state in a few lines what you want to > achieve? I can guess based on the current solution, but I'd like to hear > it from you. Please leave out rants about tools and languages etc. so we > can focus on the problem statement, and try to figure out the best > overall solution. It is basically what's written above: to produce a cross-referenced output document from a source, were, clicking on the API symbols will navigate to the place where the symbol was documented. It should allow to add exceptions, as we don't want to add cross-references for legacy symbols or helper macros, for example. This is a good example on what we want: https://linuxtv.org/downloads/v4l-dvb-apis-new/media/uapi/rc/lirc-header.html#lirc-h The only parts of the header file that will have a different color will be the symbols defined at the API. This way, it is easy for us to visually discover what stuff is not yet documented (like LIRC_MODE2_SPACE - that should be documented - and _LINUX_LIRC_H macro - that should not be documented). When something is not cross-referenced there, there's a single place to look that will explain why this was not documented (at the exceptions file). The main goal for documentation writers is to use the header file to identify the documentation gaps. For code developers, the header file works like an index to the document, where all the API can be seen altogether, and more details can easily be obtained by clicking at the links. Regard Cheers, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
