Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1197977 > unrolled thread

Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation  in struct body Jonathan Corbet <corbet@lwn.net> - 2015-08-01 13:30 +0200
    Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation  in struct body Daniel Vetter <daniel@ffwll.ch> - 2015-08-03 10:30 +0200
      Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation  in struct body Jonathan Corbet <corbet@lwn.net> - 2015-08-03 16:40 +0200
        Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation  in struct body Daniel Vetter <daniel@ffwll.ch> - 2015-08-03 17:40 +0200

#1197977 — Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

On Fri, 31 Jul 2015 18:06:45 -0300
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:

> Describing arguments at top of a struct definition works fine
> for small/medium size structs, but it definitely doesn't work well
> for struct with a huge list of elements.
> 
> Keeping the arguments list inside the struct body makes it easier
> to maintain the documentation.

Interesting approach.  I think it could make sense, but I fear pushback
from a subset of maintainers refusing to accept this mode.  I wonder what
it would take to get a consensus on allowing these in-struct comments?

I'm wondering if we need a kernel summit session on commenting
conventions, markdown-in-kerneldoc, etc?  Maybe I'll stick a proposal out
there.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [next] | [standalone]

#1198635

On Sat, Aug 01, 2015 at 01:22:10PM +0200, Jonathan Corbet wrote:
> On Fri, 31 Jul 2015 18:06:45 -0300
> Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:
> 
> > Describing arguments at top of a struct definition works fine
> > for small/medium size structs, but it definitely doesn't work well
> > for struct with a huge list of elements.
> > 
> > Keeping the arguments list inside the struct body makes it easier
> > to maintain the documentation.
> 
> Interesting approach.  I think it could make sense, but I fear pushback
> from a subset of maintainers refusing to accept this mode.  I wonder what
> it would take to get a consensus on allowing these in-struct comments?

At least in drm we have a lot of such comments (as non-kerneldoc) right
above struct members to explain some details. Common examples are:
- locks, with a description of what they protect and maybe also how they
  nest.
- vfunc ops structs, with a per-function description of what each hook
  does.
- tricky stuff which can't be described in one sentence only.

So it's not just huge structs by number of members, but huge by number of
comment lines. Trying to stuff that all into the top kerneldoc comment
means that it's much harder to jump to the right comment, and it's also
easier to ignore the comments (since it e.g. won't show up in the diff
context).

The current approach at least in drm is to duplicate comments and that
just results in inconsistency.
 
> I'm wondering if we need a kernel summit session on commenting
> conventions, markdown-in-kerneldoc, etc?  Maybe I'll stick a proposal out
> there.

Might be useful, but I'm not sure how many people really would actively
work on improving the tooling. The only comment I've seen is to maybe use
gtkdoc, but that would be a pain since it's slightly incompatible with
kerneldoc.

And it's the improved tooling I really need for my long-term plan to get
solid docs for drm & drm/i915. Next step is to start building a proper doc
writer team to make all the bits we already have into a consistent hole
(and nag developers to fill in the areas still undocumented). For that
I've already pulled Danilo's patches into the drm-intel integration tree
and I plan to use them for any further drm kerneldoc I write since we
really need them.

Thanks, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [next] | [standalone]

#1198898

On Mon, 3 Aug 2015 10:23:19 +0200
Daniel Vetter <daniel@ffwll.ch> wrote:

> > I'm wondering if we need a kernel summit session on commenting
> > conventions, markdown-in-kerneldoc, etc?  Maybe I'll stick a proposal out
> > there.  
> 
> Might be useful, but I'm not sure how many people really would actively
> work on improving the tooling. The only comment I've seen is to maybe use
> gtkdoc, but that would be a pain since it's slightly incompatible with
> kerneldoc.

The idea was to get a sense for what sort of improvements would be
useful, to begin with.  But my attempt to start a discussion on the
kernel summit list appears to have hit the ground pretty hard; I guess
that means I have free rein :)

I expect I'll apply the struct-args doc patch in the fairly near future.
Then we'll see if others complain when patches using it start to show up,
but the feature itself shouldn't break anything.  I'm *really* hoping to
take a hard look at Danilo's stuff for a 4.3 merge as well.  It should be
possible, but there's real-world obnoxiousness that is doing its best to
get in the way.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [next] | [standalone]

#1198970

On Mon, Aug 03, 2015 at 08:37:41AM -0600, Jonathan Corbet wrote:
> On Mon, 3 Aug 2015 10:23:19 +0200
> Daniel Vetter <daniel@ffwll.ch> wrote:
> 
> > > I'm wondering if we need a kernel summit session on commenting
> > > conventions, markdown-in-kerneldoc, etc?  Maybe I'll stick a proposal out
> > > there.  
> > 
> > Might be useful, but I'm not sure how many people really would actively
> > work on improving the tooling. The only comment I've seen is to maybe use
> > gtkdoc, but that would be a pain since it's slightly incompatible with
> > kerneldoc.
> 
> The idea was to get a sense for what sort of improvements would be
> useful, to begin with.  But my attempt to start a discussion on the
> kernel summit list appears to have hit the ground pretty hard; I guess
> that means I have free rein :)

Wrt feature wishlists the 3 things Danilo has worked on thus far
(hyperlinks, markdown and inline struct member kerneldoc) are really the
things I'd like to have. Of course there's room for some more
prettification, but I think that would better fit as improvements to
pandoc. One example is more flexible table handling with row/column
spanning - currently pandoc doesn't handle that in the docbook converter.

> I expect I'll apply the struct-args doc patch in the fairly near future.
> Then we'll see if others complain when patches using it start to show up,
> but the feature itself shouldn't break anything.  I'm *really* hoping to
> take a hard look at Danilo's stuff for a 4.3 merge as well.  It should be
> possible, but there's real-world obnoxiousness that is doing its best to
> get in the way.

Awesome. Missing 4.3 wouldn't be a big deal for i915 really since drm
feature freeze should happen around -rc5 anyway, so everything new I pull
in will be for 4.4 only. But getting it in early always helps, just in
case there's something unexpected.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web