[rfa/doco] Revise "Include Files" in internals doco

[Andrew Cagney <ac131313@ges.redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 169 bytes --]

Hello,

This tries to clarify GDB's include file coding policy.  It now makes a 
direct reference to opaque structures.

The rules haven't actually changes.

ok?
Andrew

[-- Attachment #2: diffs --]
[-- Type: text/plain, Size: 2187 bytes --]

2002-07-30  Andrew Cagney  <ac131313@redhat.com>
 
 	* gdbint.texinfo (Coding): Revise section "Include Files".
 
Index: doc/gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.95
diff -c -r1.95 gdbint.texinfo
*** doc/gdbint.texinfo	24 Jul 2002 23:51:36 -0000	1.95
--- doc/gdbint.texinfo	30 Jul 2002 15:30:45 -0000
***************
*** 5065,5083 ****
  
  @subsection Include Files
  
! All @file{.c} files should include @file{defs.h} first.
  
! All @file{.c} files should explicitly include the headers for any
! declarations they refer to.  They should not rely on files being
! included indirectly.
  
! With the exception of the global definitions supplied by @file{defs.h},
! a header file should explicitly include the header declaring any
! @code{typedefs} et.al.@: it refers to.
  
! @code{extern} declarations should never appear in @code{.c} files.
  
! All include files should be wrapped in:
  
  @smallexample
  #ifndef INCLUDE_FILE_NAME_H
--- 5065,5094 ----
  
  @subsection Include Files
  
! A @file{.c} file should include @file{defs.h} first.
  
! A @file{.c} file should directly include the @code{.h} file of every
! declaration and/or definition it directly refers to.  It cannot rely on
! indirect inclusion.
  
! A @file{.h} file should directly include the @code{.h} file of every
! declaration and/or definition it directly refers to.  It cannot rely on
! indirect inclusion.  Exception: The file @file{defs.h} does not need to
! be directly included.
  
! An external declaration should only appear in one include file.
  
! An external declaration should never appear in a @code{.c} file.
! Exception: a declaration for the @code{_initialize} function that
! pacifies @option{-Wmissing-declaration}.
! 
! A @code{typedef} definition should only appear in one include file.
! 
! An opaque @code{struct} declaration can appear in multiple @file{.h}
! files.  Where possible, a @file{.h} file should use an opaque
! @code{struct} declaration instead of an include.
! 
! All @file{.h} files should be wrapped in:
  
  @smallexample
  #ifndef INCLUDE_FILE_NAME_H