kern/44759: many CFATTACH_DECL* macros, little documentation

[riz%NetBSD.org@localhost]

>Number:         44759
>Category:       kern
>Synopsis:       CFATTACH_DECL* macros should be better documented
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Tue Mar 22 23:25:01 +0000 2011
>Originator:     riz%NetBSD.org@localhost
>Release:        NetBSD 5.99.48
>Organization:
        
>Environment:
        
        
System: NetBSD netbsd-i386 5.99.48 NetBSD 5.99.48 (TUTORIAL) #1: Tue Mar 22 
11:56:44 PDT 2011 riz@netbsd-i386:/usr/src/sys/arch/i386/compile/TUTORIAL i386
Architecture: i386
Machine: i386
>Description:
        I'm currently working with the kernel development tutorials,
trying to update them where appropriate for NetBSD (while also using them
to polish my skills).  I wanted to add (for example) the ability to detach
to the pseudo-device tutorial, and it seems like I need to add a CFATTACH_DECL()
(which I gleaned by looking at other pseudo-device code).  However, I could
not find any documentation to help me decide _which_ of the variants
to use.  In device.h, I see:

CFATTACH_DECL
CFATTACH_DECL_NEW
CFATTACH_DECL2_NEW
CFATTACH_DECL3_NEW.

After looking around (apropos was no help), I found some documentation of
CFATTACH_DECL in driver(9), but no mention of alternatives.

>How-To-Repeat:
        
>Fix:
        I humbly suggest:

        - xref CFATTACH_DECL to driver(9) somehow, so it's findable from
        apropos.

        - add some discussion of the variants, either to driver(9) or
        comments in driver. I don't have any suggested wording, because
        I'm still pretty fuzzy on the concept myself.

>Unformatted: