Re: [U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h
Hi Simon, On Wed, May 30, 2018 at 9:18 PM, Simon Glass wrote: > Hi Mario, > > On 28 May 2018 at 07:01, Mario Six wrote: >> Hi Simon, >> >> On Fri, May 25, 2018 at 4:41 AM, Simon Glass wrote: >>> +Marex >>> >>> Hi Mario, >>> >>> On 23 May 2018 at 08:07, Mario Six wrote: The comments in misc.h are not in kernel-doc format. Correct the format. Signed-off-by: Mario Six --- 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
Re: [U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h
Hi Mario, On 28 May 2018 at 07:01, Mario Six wrote: > Hi Simon, > > On Fri, May 25, 2018 at 4:41 AM, Simon Glass wrote: >> +Marex >> >> Hi Mario, >> >> On 23 May 2018 at 08:07, Mario Six wrote: >>> The comments in misc.h are not in kernel-doc format. Correct the format. >>> >>> Signed-off-by: Mario Six >>> >>> --- >>> >>> 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 ___ U-Boot mailing list U-Boot@lists.denx.de https://lists.denx.de/listinfo/u-boot
Re: [U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h
Hi Simon, On Fri, May 25, 2018 at 4:41 AM, Simon Glasswrote: > +Marex > > Hi Mario, > > On 23 May 2018 at 08:07, Mario Six wrote: >> The comments in misc.h are not in kernel-doc format. Correct the format. >> >> Signed-off-by: Mario Six >> >> --- >> >> 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 ___ U-Boot mailing list U-Boot@lists.denx.de https://lists.denx.de/listinfo/u-boot
Re: [U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h
+Marex Hi Mario, On 23 May 2018 at 08:07, Mario Sixwrote: > The comments in misc.h are not in kernel-doc format. Correct the format. > > Signed-off-by: Mario Six > > --- > > 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. Regards, Simon ___ U-Boot mailing list U-Boot@lists.denx.de https://lists.denx.de/listinfo/u-boot