lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Date:	Tue, 22 Apr 2008 18:19:42 -0700
From:	Randy Dunlap <randy.dunlap@...cle.com>
To:	Jason Wessel <jason.wessel@...driver.com>
Cc:	Randy Dunlap <RANDY.DUNLAP@...cle.com>,
	Andrew Morton <akpm@...ux-foundation.org>, mingo@...e.hu,
	linux-kernel@...r.kernel.org
Subject: Re: kgdb: core

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@...cle.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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Powered by blists - more mailing lists