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

[Simon Glass]

Hi Mario,

On 28 May 2018 at 07:01, Mario Six <mario.six at gdsys.cc> wrote:
> 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

OK how about adding it to the README then? Also the DocBook scripts
need to be updated I think.

Regards,
Simon