[U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h

[Mario Six]

Hi Simon,

On Fri, May 25, 2018 at 4:41 AM, Simon Glass <sjg at chromium.org> wrote:
> +Marex
>
> Hi Mario,
>
> On 23 May 2018 at 08:07, Mario Six <mario.six at gdsys.cc> wrote:
>> The comments in misc.h are not in kernel-doc format. Correct the format.
>>
>> Signed-off-by: Mario Six <mario.six at gdsys.cc>
>>
>> ---
>>
>> v2 -> v3:
>> New in v3
>>
>> ---
>>  include/misc.h | 66 +++++++++++++++++++++++++++++++---------------------------
>>  1 file changed, 35 insertions(+), 31 deletions(-)
>>
>
> Not another format?! I have been following what I thought was docbook
> format as proposed by Marek a few years ago.
>

Well, others seem to think different. Michal pointed out in [1] that the
comments were very close to kerneldoc, but not quiet, and proposed to change
the format to make them comply. This seems reasonable, since the kerneldoc
utility is in the tree after all.

As for the docbook format: That was imported from the Linux kernel, and the
kernel guys subsequently abandoned the docbook format in favor of Sphinx-based
documentation. So, you could argue that the docbook format is obsolete (also,
from what I see there were only ever two docbook documents written in U-Boot,
so the success was limited).

But that's actually a good question: Is there a preferred or even mandatory doc
format in use? If that's the case, it would certainly be nice if it was
documented somewhere (or even if there was an automated linter akin to
kerneldoc, for example).

[1] http://patchwork.ozlabs.org/patch/905733/#1902178

> Regards,
> Simon

Best regards,
Mario