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

[Mario Six]

Hi Simon,

On Wed, May 30, 2018 at 9:18 PM, Simon Glass <sjg at chromium.org> wrote:
> 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.
>

The best way to update the DocBook scripts would probably be to pull in the
sphinx-based scripts, and migrate the DocBook files to sphinx. I'll check how
complicated that would be.

> Regards,
> Simon
>

Best regards,
Mario