Re: [doc RFA] Switch to GCC coding style [Re: [patch] initial OpenCL C language support]

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 2 Nov 2010 18:22:46 +0100
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: gdb-patches@sourceware.org, Joel Brobecker <brobecker@adacore.com>,        Ken Werner <ken@linux.vnet.ibm.com>, Tom Tromey <tromey@redhat.com>,        Pedro Alves <pedro@codesourcery.com>
> 
> On Tue, 02 Nov 2010 18:04:39 +0100, Doug Evans wrote:
> > There are lots of things on the gcc codingconventions page that need
> > to be converted (e.g., gcc_assert),
> 
> Done.
> 
> > or revised (e.g., prototypes for _initialize_foo fns can appear in .c files
> > (and should *only* appear in .c files)).
> 
> I do not see a current GDB doc problem with this (+it may be offtopic for this
> patch).
> 
> 
> Thanks,
> Jan

Are you submitting this for doc review, or will we discuss the issue
first?  Or maybe the issue is already decided?  Please help me out
here.

> -@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 the GCC Coding Conventions, available from
> +@url{http://gcc.gnu.org/codingconventions.html}.  @value{GDBN} takes a strict
> +interpretation of the standard; in general, when the GCC conventions recommend
> +a practice but do not require it, @value{GDBN} requires it.

The old text talked about "GNU coding _standards_", so it was
understandable when it later mentioned "interpretation of the
standard".  But you replaced "standards" with "Conventions", so now
"interpretation of the standard" begs the question: "what standard?".

Also, this is actually the first violation in GDB history of the GCC
Conventions, which request to use @uref, not @url for references to
Web pages. ;-)

> -The standard GNU recommendations for formatting must be followed
> +The standard GCC recommendations for formatting must be followed
>  strictly.

There are no "recommendations for formatting" that I could spot in the
GCC Conventions.  At least they are not called that.

> -The standard GNU requirements on comments must be followed strictly.
> +The standard GCC requirements on comments must be followed strictly.

I see no requirements on comments in the GCC Conventions.  But even if
I missed something, why single out only this part?

> +@code{gcc_assert} references in GCC Coding Conventions should be replaced by
> +@code{gdb_assert}.  @code{gcc_unreachable} should be replaced by
> +@code{gdb_assert_not_reached}.  Standard @code{<ctype.h>} header file and its
> +functions can and should be used.

I don't think this is enough, sorry.  The GCC Conventions mention a
lot of details that are utterly inapplicable to GDB.  The exceptions
you mention are just a drop in that sea.  What about references to
ERROR_MARK, RTL, --param arguments, what about fastjar and boehm-gc?
And those are just a few random examples.

On balance, I think we should simply have our own coherent document.
It can copy verbatim all the stuff that is relevant to GDB, but it
should include the above renames, and it should omit everything that
is irrelevant.  Any other way, we will just confuse potential
contributors: it is perhaps easy for us old-timers to distinguish
between the relevant and the rest, but for a newbie contributor it
could be an impossible requirement.  To say nothing of the fact that
they will now have to read two documents instead of 1.

Thanks.