| Message ID | 20161114115825.22050-8-daniel.vetter@ffwll.ch (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Mon, Nov 14, 2016 at 12:58:22PM +0100, Daniel Vetter wrote: > kerneldoc expects the comment next to definitions, otherwise it can't > pick up exported vs. internal stuff. > > This fixes a warning from the doc build done with: > > $ make DOCBOOKS="" htmldocs > > Fixes: d8187177b0b1 ("drm: add helper for printing to log or seq_file") > Cc: Rob Clark <robdclark@gmail.com> > Cc: Sean Paul <seanpaul@chromium.org> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Oh well, I liked the practice of having interface descriptions in the headers. If they are in the body, I may as well just read the code. Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk> -Chris
On Tue, Nov 15, 2016 at 10:37:26AM +0000, Chris Wilson wrote: > On Mon, Nov 14, 2016 at 12:58:22PM +0100, Daniel Vetter wrote: > > kerneldoc expects the comment next to definitions, otherwise it can't > > pick up exported vs. internal stuff. > > > > This fixes a warning from the doc build done with: > > > > $ make DOCBOOKS="" htmldocs > > > > Fixes: d8187177b0b1 ("drm: add helper for printing to log or seq_file") > > Cc: Rob Clark <robdclark@gmail.com> > > Cc: Sean Paul <seanpaul@chromium.org> > > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> > > Oh well, I liked the practice of having interface descriptions in the > headers. If they are in the body, I may as well just read the code. I'm divided. On one hand it makes it more easily readable for users of the code&functions. Otoh having it closer might increase the odds that it's not forgotten when the semantics change. Personally I just have lots of windows open, with both code and rendered docs ... -Daniel
On Tue, Nov 15, 2016 at 12:53:48PM +0100, Daniel Vetter wrote: > On Tue, Nov 15, 2016 at 10:37:26AM +0000, Chris Wilson wrote: > > On Mon, Nov 14, 2016 at 12:58:22PM +0100, Daniel Vetter wrote: > > > kerneldoc expects the comment next to definitions, otherwise it can't > > > pick up exported vs. internal stuff. > > > > > > This fixes a warning from the doc build done with: > > > > > > $ make DOCBOOKS="" htmldocs > > > > > > Fixes: d8187177b0b1 ("drm: add helper for printing to log or seq_file") > > > Cc: Rob Clark <robdclark@gmail.com> > > > Cc: Sean Paul <seanpaul@chromium.org> > > > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> > > > > Oh well, I liked the practice of having interface descriptions in the > > headers. If they are in the body, I may as well just read the code. > > I'm divided. On one hand it makes it more easily readable for users of the > code&functions. Otoh having it closer might increase the odds that it's > not forgotten when the semantics change. Personally I just have lots of > windows open, with both code and rendered docs ... And merged up to this one, with addressing your feedback re copyright notices. Somehow there's a nasty conflict with the extraction in patch 8 that I haven't figured out yet, needs more coffee. Thanks for your review. -Daniel
diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index a54ac97510b3..e35920db1f4c 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -366,7 +366,7 @@ Printer .. kernel-doc:: include/drm/drm_print.h :internal: -.. kernel-doc:: include/drm/drm_print.h +.. kernel-doc:: drivers/gpu/drm/drm_print.c :export: diff --git a/drivers/gpu/drm/drm_print.c b/drivers/gpu/drm/drm_print.c index 34eb85618b76..ad3caaa1f48b 100644 --- a/drivers/gpu/drm/drm_print.c +++ b/drivers/gpu/drm/drm_print.c @@ -40,6 +40,11 @@ void __drm_printfn_info(struct drm_printer *p, struct va_format *vaf) } EXPORT_SYMBOL(__drm_printfn_info); +/** + * drm_printf - print to a &drm_printer stream + * @p: the &drm_printer + * @f: format string + */ void drm_printf(struct drm_printer *p, const char *f, ...) { struct va_format vaf; diff --git a/include/drm/drm_print.h b/include/drm/drm_print.h index 475ffe3730e9..1adf84aea622 100644 --- a/include/drm/drm_print.h +++ b/include/drm/drm_print.h @@ -74,11 +74,6 @@ struct drm_printer { void __drm_printfn_seq_file(struct drm_printer *p, struct va_format *vaf); void __drm_printfn_info(struct drm_printer *p, struct va_format *vaf); -/** - * drm_printf - print to a &drm_printer stream - * @p: the &drm_printer - * @f: format string - */ void drm_printf(struct drm_printer *p, const char *f, ...);
kerneldoc expects the comment next to definitions, otherwise it can't pick up exported vs. internal stuff. This fixes a warning from the doc build done with: $ make DOCBOOKS="" htmldocs Fixes: d8187177b0b1 ("drm: add helper for printing to log or seq_file") Cc: Rob Clark <robdclark@gmail.com> Cc: Sean Paul <seanpaul@chromium.org> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> --- Documentation/gpu/drm-internals.rst | 2 +- drivers/gpu/drm/drm_print.c | 5 +++++ include/drm/drm_print.h | 5 ----- 3 files changed, 6 insertions(+), 6 deletions(-)