Messages in this thread |  | | | Date | Mon, 21 Apr 2008 21:46:36 -0700 | | From | Andrew Morton <> | | Subject | Re: kgdb: core | |
> On Mon, 21 Apr 2008 16:12:52 +0200 Ingo Molnar <mingo@elte.hu> wrote:
> > So please
> >
> > a) make this a kerneldoc comment and
> >
> > b) remove the kerneldoc at the definition site(s).
> >
> > (alternative: teach the kerneldoc system to go fishing in the various
> > arch directories to find the appropriate documentation, but I don't
> > know enough about kerneldoc to be able say anything about that).
>
> well there's lkml feedback ping-pong effect here. It was pointed out in
> earlier kgdb review that it's an "error" to put kerneldoc into header
> files.
It is, normally. Nobody thought about this case.
> I pointed out that it makes no sense to do otherwise but removed
> the kerneldoc annotation to resolve the "objection".
Duplicating the same stuff in multiple places is the larger sin. It sounds
like the best compromise would be to kernel-doc the interface in the .h
file and remove the duplicated comments from .c.
Or perhaps we kernel-doc the interface in the x86 .c files and leave it at
that - people should go there to find the docs. Problem is, this will
presumably generate bad results if one builds the formal kerneldoc output
for a different architecture. The kerneldoc system could of course fix
this somehow, but I don't know what shape it would take nor how much work
it would be.
|  |