Hi Simon, On Wed, May 30, 2018 at 9:18 PM, Simon Glass <s...@chromium.org> wrote: > Hi Mario, > > On 28 May 2018 at 07:01, Mario Six <mario....@gdsys.cc> wrote: >> Hi Simon, >> >> On Fri, May 25, 2018 at 4:41 AM, Simon Glass <s...@chromium.org> wrote: >>> +Marex >>> >>> Hi Mario, >>> >>> On 23 May 2018 at 08:07, Mario Six <mario....@gdsys.cc> wrote: >>>> The comments in misc.h are not in kernel-doc format. Correct the format. >>>> >>>> Signed-off-by: Mario Six <mario....@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 _______________________________________________ U-Boot mailing list U-Boot@lists.denx.de https://lists.denx.de/listinfo/u-boot