Re: PATCH to document init_xxx and other function naming conventions

[Per Bothner <per at bothner dot com>]

I'm not getting any strong consensus on where naming conventions
should be documented.  I'd like to check in this revised patch.  OK?

Joseph S. Myers wrote:

> > If you're referring to something besides the capitalization of GCC
> > (that Gaby noted) please be more specific.
>
> TeX quotes and dashes.

Oops.  Should be fixed now.
--
	--Per Bothner
per@bothner.com   http://per.bothner.com/

Index: gccint.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/gccint.texi,v
retrieving revision 1.10
diff -u -r1.10 gccint.texi
--- gccint.texi	15 Mar 2003 19:54:10 -0000	1.10
+++ gccint.texi	9 Aug 2003 22:38:23 -0000
@@ -142,6 +142,7 @@
 * Interface::       Function-call interface of GCC output.
 * Libgcc::          Low-level runtime library used by GCC.
 * Languages::       Languages for which GCC front ends are written.
+* Conventions::     Coding conventions and styles of GCC.
 * Source Tree::     GCC source tree structure and build system.
 * Passes::          Order of passes, what they do, and what each file is for.
 * Trees::           The source representation used by the C and C++ front ends.
@@ -171,6 +172,7 @@
 @include interface.texi
 @include libgcc.texi
 @include languages.texi
+@include codingconv.texi
 @include sourcebuild.texi
 @include passes.texi
 @include c-tree.texi
Index: codingconv.texi
===================================================================
RCS file: codingconv.texi
diff -N codingconv.texi
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ codingconv.texi	9 Aug 2003 22:38:23 -0000
@@ -0,0 +1,48 @@
+@c Copyright (C) 2003 Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gccint.texi.
+
+@node Conventions
+@chapter Coding Conventions and Style of Gcc
+@cindex Conventions
+@cindex Styles
+
+Code should follow the
+@uref{http://gcc.gnu.org/codingconventions.html, GCC Coding Conventions},
+as well as the general
+@uref{http://www.gnu.org/prep/standards_toc.html, GNU Coding Standards}.
+
+Code should follow ISO C89--GCC can no longer be compiled
+using old pre-ANSI ``K&R'' C compilers.
+All functions must have prototypes.
+
+Note that most of GCC is compiled such that warnings are errors,
+so don't be sloppy!
+
+@section Function names
+
+GCC follows certain conventions when it comes to naming functions.
+
+@code{expand_@var{xxx}}: Take tree node(s) and generate rtl.
+
+@code{emit_@var{xxx}}: Low-level functions for creating rtl instructions.
+
+@subsection Initialization
+
+We are working on letting GCC be used in different modes, where it
+can compile multiple input files or create multiple output files
+in a single run.  So when initializing a data structure,
+it is becoming important to clearly indicate when and how
+frequently that initialization needs to happen.
+
+@code{init_@var{xxx}_once}:  Such a function is only ever run once,
+usually when the compiler starts.
+
+@code{init_@var{xxx}_eachsrc}:  Such a function is run once for
+each top-level source file (``main module''), before reading the source file.
+
+@code{init_@var{xxx}_eachasm}:  Such a function is run once each time before
+we open an assembler file for output.
+
+@code{init_@var{xxx}_eachfn}:  Such a function is run once each at the
+start of processing a new function.