* gdbint.texinfo (Misc Guidelines): Renamed from Coding.

	All references updated.  Correct sections marked as subsections.
	(Coding Standards): New chapter.  Move the coding standard related
	subsections here.  Add section on Python coding standards.

2 files changed, 247 insertions, 216 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index c2e45ae..6a3d962 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,10 @@
+2010-10-20  Doug Evans  <dje@google.com>
+
+	* gdbint.texinfo (Misc Guidelines): Renamed from Coding.
+	All references updated.  Correct sections marked as subsections.
+	(Coding Standards): New chapter.  Move the coding standard related
+	subsections here.  Add section on Python coding standards.
+
 2010-10-13  Doug Evans  <dje@google.com>
 
 	* gdb.texinfo (Python): Add "Python modules".
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index 54187dd..4a112aa 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -83,7 +83,8 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
 * Target Vector Definition::
 * Native Debugging::
 * Support Libraries::
-* Coding::
+* Coding Standards::
+* Misc Guidelines::
 * Porting GDB::
 * Versions and Branches::
 * Start of New Year Procedure::
@@ -1322,9 +1323,9 @@ be signaled.
 
 @deftypefun {struct cleanup *} make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
 This function first opens the tuple and then establishes a cleanup
-(@pxref{Coding, Cleanups}) to close the tuple.  It provides a convenient
-and correct implementation of the non-portable@footnote{The function
-cast is not portable ISO C.} code sequence:
+(@pxref{Misc Guidelines, Cleanups}) to close the tuple.
+It provides a convenient and correct implementation of the
+non-portable@footnote{The function cast is not portable ISO C.} code sequence:
 @smallexample
 struct cleanup *old_cleanup;
 ui_out_tuple_begin (uiout, "...");
@@ -1349,7 +1350,8 @@ be signaled.
 
 @deftypefun {struct cleanup *} make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
 Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
-opens a list and then establishes cleanup (@pxref{Coding, Cleanups})
+opens a list and then establishes cleanup
+(@pxref{Misc Guidelines, Cleanups})
 that will close the list.
 @end deftypefun
 
@@ -5756,9 +5758,235 @@ Binary search the array.
 
 @section include
 
-@node Coding
+@node Coding Standards
 
-@chapter Coding
+@chapter Coding Standards
+@cindex coding standards
+
+@section @value{GDBN} C Coding Standards
+
+@value{GDBN} follows the GNU coding standards, as described in
+@file{etc/standards.texi}.  This file is also available for anonymous
+FTP from GNU archive sites.  @value{GDBN} takes a strict interpretation
+of the standard; in general, when the GNU standard recommends a practice
+but does not require it, @value{GDBN} requires it.
+
+@value{GDBN} follows an additional set of coding standards specific to
+@value{GDBN}, as described in the following sections.
+
+@subsection ISO C
+
+@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
+compiler.
+
+@value{GDBN} does not assume an ISO C or POSIX compliant C library.
+
+@subsection Formatting
+
+@cindex source code formatting
+The standard GNU recommendations for formatting must be followed
+strictly.
+
+A function declaration should not have its name in column zero.  A
+function definition should have its name in column zero.
+
+@smallexample
+/* Declaration */
+static void foo (void);
+/* Definition */
+void
+foo (void)
+@{
+@}
+@end smallexample
+
+@emph{Pragmatics: This simplifies scripting.  Function definitions can
+be found using @samp{^function-name}.}
+
+There must be a space between a function or macro name and the opening
+parenthesis of its argument list (except for macro definitions, as
+required by C).  There must not be a space after an open paren/bracket
+or before a close paren/bracket.
+
+While additional whitespace is generally helpful for reading, do not use
+more than one blank line to separate blocks, and avoid adding whitespace
+after the end of a program line (as of 1/99, some 600 lines had
+whitespace after the semicolon).  Excess whitespace causes difficulties
+for @code{diff} and @code{patch} utilities.
+
+Pointers are declared using the traditional K&R C style:
+
+@smallexample
+void *foo;
+@end smallexample
+
+@noindent
+and not:
+
+@smallexample
+void * foo;
+void* foo;
+@end smallexample
+
+@subsection Comments
+
+@cindex comment formatting
+The standard GNU requirements on comments must be followed strictly.
+
+Block comments must appear in the following form, with no @code{/*}- or
+@code{*/}-only lines, and no leading @code{*}:
+
+@smallexample
+/* Wait for control to return from inferior to debugger.  If inferior
+   gets a signal, we may decide to start it up again instead of
+   returning.  That is why there is a loop in this function.  When
+   this function actually returns it means the inferior should be left
+   stopped and @value{GDBN} should read more commands.  */
+@end smallexample
+
+(Note that this format is encouraged by Emacs; tabbing for a multi-line
+comment works correctly, and @kbd{M-q} fills the block consistently.)
+
+Put a blank line between the block comments preceding function or
+variable definitions, and the definition itself.
+
+In general, put function-body comments on lines by themselves, rather
+than trying to fit them into the 20 characters left at the end of a
+line, since either the comment or the code will inevitably get longer
+than will fit, and then somebody will have to move it anyhow.
+
+@subsection C Usage
+
+@cindex C data types
+Code must not depend on the sizes of C data types, the format of the
+host's floating point numbers, the alignment of anything, or the order
+of evaluation of expressions.
+
+@cindex function usage
+Use functions freely.  There are only a handful of compute-bound areas
+in @value{GDBN} that might be affected by the overhead of a function
+call, mainly in symbol reading.  Most of @value{GDBN}'s performance is
+limited by the target interface (whether serial line or system call).
+
+However, use functions with moderation.  A thousand one-line functions
+are just as hard to understand as a single thousand-line function.
+
+@emph{Macros are bad, M'kay.}
+(But if you have to use a macro, make sure that the macro arguments are
+protected with parentheses.)
+
+@cindex types
+
+Declarations like @samp{struct foo *} should be used in preference to
+declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
+
+@subsection Function Prototypes
+@cindex function prototypes
+
+Prototypes must be used when both @emph{declaring} and @emph{defining}
+a function.  Prototypes for @value{GDBN} functions must include both the
+argument type and name, with the name matching that used in the actual
+function definition.
+
+All external functions should have a declaration in a header file that
+callers include, except for @code{_initialize_*} functions, which must
+be external so that @file{init.c} construction works, but shouldn't be
+visible to random source files.
+
+Where a source file needs a forward declaration of a static function,
+that declaration must appear in a block near the top of the source file.
+
+@subsection File Names
+
+Any file used when building the core of @value{GDBN} must be in lower
+case.  Any file used when building the core of @value{GDBN} must be 8.3
+unique.  These requirements apply to both source and generated files.
+
+@emph{Pragmatics: The core of @value{GDBN} must be buildable on many
+platforms including DJGPP and MacOS/HFS.  Every time an unfriendly file
+is introduced to the build process both @file{Makefile.in} and
+@file{configure.in} need to be modified accordingly.  Compare the
+convoluted conversion process needed to transform @file{COPYING} into
+@file{copying.c} with the conversion needed to transform
+@file{version.in} into @file{version.c}.}
+
+Any file non 8.3 compliant file (that is not used when building the core
+of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
+
+@emph{Pragmatics: This is clearly a compromise.}
+
+When @value{GDBN} has a local version of a system header file (ex
+@file{string.h}) the file name based on the POSIX header prefixed with
+@file{gdb_} (@file{gdb_string.h}).  These headers should be relatively
+independent: they should use only macros defined by @file{configure},
+the compiler, or the host; they should include only system headers; they
+should refer only to system types.  They may be shared between multiple
+programs, e.g.@: @value{GDBN} and @sc{gdbserver}.
+
+For other files @samp{-} is used as the separator.
+
+@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
+#define INCLUDE_FILE_NAME_H
+header body
+#endif
+@end smallexample
+
+@section @value{GDBN} Python Coding Standards
+
+@value{GDBN} follows the published @code{Python} coding standards in
+@uref{http://www.python.org/dev/peps/pep-0008/, @code{PEP008}}.
+
+In addition, the guidelines in the
+@uref{http://google-styleguide.googlecode.com/svn/trunk/pyguide.html,
+Google Python Style Guide} are also followed where they do not
+conflict with @code{PEP008}.
+
+@subsection @value{GDBN}-specific exceptions
+
+There are a few exceptions to the published standards.
+They exist mainly for consistency with the @code{C} standards.
+
+@c It is expected that there are a few more exceptions,
+@c so we use itemize here.
+
+@itemize @bullet
+
+@item
+Use @code{FIXME} instead of @code{TODO}.
+
+@end itemize
+
+@node Misc Guidelines
+
+@chapter Misc Guidelines
 
 This chapter covers topics that are lower-level than the major
 algorithms of @value{GDBN}.
@@ -5995,28 +6223,7 @@ finish by printing a newline, to flush the wrap buffer, before switching
 to unfiltered (@code{printf}) output.  Symbol reading routines that
 print warnings are a good example.
 
-@section @value{GDBN} Coding Standards
-@cindex coding standards
-
-@value{GDBN} follows the GNU coding standards, as described in
-@file{etc/standards.texi}.  This file is also available for anonymous
-FTP from GNU archive sites.  @value{GDBN} takes a strict interpretation
-of the standard; in general, when the GNU standard recommends a practice
-but does not require it, @value{GDBN} requires it.
-
-@value{GDBN} follows an additional set of coding standards specific to
-@value{GDBN}, as described in the following sections.
-
-
-@subsection ISO C
-
-@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
-compiler.
-
-@value{GDBN} does not assume an ISO C or POSIX compliant C library.
-
-
-@subsection Memory Management
+@section Memory Management
 
 @value{GDBN} does not use the functions @code{malloc}, @code{realloc},
 @code{calloc}, @code{free} and @code{asprintf}.
@@ -6054,7 +6261,7 @@ functions such as @code{sprintf} are very prone to buffer overflow
 errors.}
 
 
-@subsection Compiler Warnings
+@section Compiler Warnings
 @cindex compiler warnings
 
 With few exceptions, developers should avoid the configuration option
@@ -6109,124 +6316,7 @@ currently too noisy to enable with @samp{-Werror}.
 
 @end table
 
-@subsection Formatting
-
-@cindex source code formatting
-The standard GNU recommendations for formatting must be followed
-strictly.
-
-A function declaration should not have its name in column zero.  A
-function definition should have its name in column zero.
-
-@smallexample
-/* Declaration */
-static void foo (void);
-/* Definition */
-void
-foo (void)
-@{
-@}
-@end smallexample
-
-@emph{Pragmatics: This simplifies scripting.  Function definitions can
-be found using @samp{^function-name}.}
-
-There must be a space between a function or macro name and the opening
-parenthesis of its argument list (except for macro definitions, as
-required by C).  There must not be a space after an open paren/bracket
-or before a close paren/bracket.
-
-While additional whitespace is generally helpful for reading, do not use
-more than one blank line to separate blocks, and avoid adding whitespace
-after the end of a program line (as of 1/99, some 600 lines had
-whitespace after the semicolon).  Excess whitespace causes difficulties
-for @code{diff} and @code{patch} utilities.
-
-Pointers are declared using the traditional K&R C style:
-
-@smallexample
-void *foo;
-@end smallexample
-
-@noindent
-and not:
-
-@smallexample
-void * foo;
-void* foo;
-@end smallexample
-
-@subsection Comments
-
-@cindex comment formatting
-The standard GNU requirements on comments must be followed strictly.
-
-Block comments must appear in the following form, with no @code{/*}- or
-@code{*/}-only lines, and no leading @code{*}:
-
-@smallexample
-/* Wait for control to return from inferior to debugger.  If inferior
-   gets a signal, we may decide to start it up again instead of
-   returning.  That is why there is a loop in this function.  When
-   this function actually returns it means the inferior should be left
-   stopped and @value{GDBN} should read more commands.  */
-@end smallexample
-
-(Note that this format is encouraged by Emacs; tabbing for a multi-line
-comment works correctly, and @kbd{M-q} fills the block consistently.)
-
-Put a blank line between the block comments preceding function or
-variable definitions, and the definition itself.
-
-In general, put function-body comments on lines by themselves, rather
-than trying to fit them into the 20 characters left at the end of a
-line, since either the comment or the code will inevitably get longer
-than will fit, and then somebody will have to move it anyhow.
-
-@subsection C Usage
-
-@cindex C data types
-Code must not depend on the sizes of C data types, the format of the
-host's floating point numbers, the alignment of anything, or the order
-of evaluation of expressions.
-
-@cindex function usage
-Use functions freely.  There are only a handful of compute-bound areas
-in @value{GDBN} that might be affected by the overhead of a function
-call, mainly in symbol reading.  Most of @value{GDBN}'s performance is
-limited by the target interface (whether serial line or system call).
-
-However, use functions with moderation.  A thousand one-line functions
-are just as hard to understand as a single thousand-line function.
-
-@emph{Macros are bad, M'kay.}
-(But if you have to use a macro, make sure that the macro arguments are
-protected with parentheses.)
-
-@cindex types
-
-Declarations like @samp{struct foo *} should be used in preference to
-declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
-
-
-@subsection Function Prototypes
-@cindex function prototypes
-
-Prototypes must be used when both @emph{declaring} and @emph{defining}
-a function.  Prototypes for @value{GDBN} functions must include both the
-argument type and name, with the name matching that used in the actual
-function definition.
-
-All external functions should have a declaration in a header file that
-callers include, except for @code{_initialize_*} functions, which must
-be external so that @file{init.c} construction works, but shouldn't be
-visible to random source files.
-
-Where a source file needs a forward declaration of a static function,
-that declaration must appear in a block near the top of the source file.
-
-
-@subsection Internal Error Recovery
+@section Internal Error Recovery
 
 During its execution, @value{GDBN} can encounter two types of errors.
 User errors and internal errors.  User errors include not only a user
@@ -6245,76 +6335,11 @@ the code detected a user error, recovered from it and issued a
 @code{warning} or the code failed to correctly recover from the user
 error and issued an @code{internal_error}.}
 
-@subsection Command Names
+@section Command Names
 
 GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}.
 
-@subsection File Names
-
-Any file used when building the core of @value{GDBN} must be in lower
-case.  Any file used when building the core of @value{GDBN} must be 8.3
-unique.  These requirements apply to both source and generated files.
-
-@emph{Pragmatics: The core of @value{GDBN} must be buildable on many
-platforms including DJGPP and MacOS/HFS.  Every time an unfriendly file
-is introduced to the build process both @file{Makefile.in} and
-@file{configure.in} need to be modified accordingly.  Compare the
-convoluted conversion process needed to transform @file{COPYING} into
-@file{copying.c} with the conversion needed to transform
-@file{version.in} into @file{version.c}.}
-
-Any file non 8.3 compliant file (that is not used when building the core
-of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
-
-@emph{Pragmatics: This is clearly a compromise.}
-
-When @value{GDBN} has a local version of a system header file (ex
-@file{string.h}) the file name based on the POSIX header prefixed with
-@file{gdb_} (@file{gdb_string.h}).  These headers should be relatively
-independent: they should use only macros defined by @file{configure},
-the compiler, or the host; they should include only system headers; they
-should refer only to system types.  They may be shared between multiple
-programs, e.g.@: @value{GDBN} and @sc{gdbserver}.
-
-For other files @samp{-} is used as the separator.
-
-
-@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
-#define INCLUDE_FILE_NAME_H
-header body
-#endif
-@end smallexample
-
-
-@subsection Clean Design and Portable Implementation
+@section Clean Design and Portable Implementation
 
 @cindex design
 In addition to getting the syntax right, there's the little question of
@@ -6448,7 +6473,6 @@ All debugging code must be controllable using the @samp{set debug
 messages.  Use @code{fprintf_unfiltered(gdb_stdlog, ...}.  Do not use
 @code{#ifdef DEBUG}.
 
-
 @node Porting GDB
 
 @chapter Porting @value{GDBN}