Re: kgdb: core

[Randy Dunlap <randy.dunlap@oracle.com>]

On Tue, 22 Apr 2008 16:19:55 -0500 Jason Wessel wrote:

> Randy Dunlap wrote:
> > --- Original Message --- (akpm wrote:)
> >>> On Tue, 22 Apr 2008 08:25:19 -0700 Randy Dunlap
> <randy.dunlap@oracle.com> wrote:
> >>>
> >>> kernel-doc output doesn't depend on build $ARCH.
> >> Ah, interesting.  I made an ass of u and me.
> >>
> >> In that case documentng them in x86 .c and leaving all other definitions
> >> and declarations uncommented sounds the way to go?  
> >
> > Yes, that would be fine and traditional (historical).
> >
> > ~Randy
> >
> 
> So is the summary here that we cannot just document the actual
> interface API in the incude/linux/kgdb.h?

The summary is that we prefer for kernel-doc to be placed at (function
etc.) definition/implementation sites, not at declaration sites.
However, I'm sure that there are exceptions to this.

> The problem I had here was pretty simple in that not all of the
> functions in the API are used by all the archs.  It seemed pretty
> reasonable at the time to just document everything in the .h file
> because it was more for the folks who wanted to add kgdb support to an
> arch and of little to no use to end users of kgdb.

I see.  That could pose a problem.

And there is not any one $arch that does use the complete API?
If so, all of the kernel-doc could be in that $arch.

> The mainline only has a small chunk of the docs right now because not
> all of kgdb is merged.  I was just hoping it was real easy to generate
> some reasonable looking docs.  The docs for all the kgdb code that
> exists (in mainline and not in mainline) can be viewed here as an
> example.
> 
> http://kernel.org/pub/linux/kernel/people/jwessel/kgdb/

If it poses an extreme hardship on you to conform to the
norms/expectations, so be it.  It won't kill anything AFAIK.
(i.e., I won't object.)

---
~Randy