[Bug fortran/51820] New: [doc] underscoring documentation incorrect

["jb at gcc dot gnu.org" <gcc-bugzilla at gcc dot gnu dot org>]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=51820

             Bug #: 51820
           Summary: [doc] underscoring documentation incorrect
    Classification: Unclassified
           Product: gcc
           Version: unknown
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: fortran
        AssignedTo: unassigned@gcc.gnu.org
        ReportedBy: jb@gcc.gnu.org


In the documentation for -fno-underscoring it is said: "With -funderscoring in
effect, GNU Fortran appends one underscore to external names with no
underscores.". The last part is needlessly confusing, as the underscore is
appended regardless of whether the name contains underscore or not. From the
code:

      if (gfc_option.flag_underscoring)
        {
          has_underscore = strchr (sym->name, '_') != 0;
          if (gfc_option.flag_second_underscore && has_underscore)
            snprintf (name, sizeof name, "%s__", sym->name);
          else
            snprintf (name, sizeof name, "%s_", sym->name);
          return get_identifier (name);
        }
      else
        return get_identifier (sym->name);

Also, the example following the description is also incorrect:

"""
is implemented as something akin to:

          i = j_() + max_count__(&my_var__, &lvar);
"""

max_count will not have two underscores, unless -fsecond-underscore is in
effect. Same for my_var. And as the example description says that my_var and
lvar are local  variables, they should not be mangled (or they both should be).

In the documentation for -fsecond-underscore it says: "GNU Fortran also appends
two underscores to internal names with underscores to avoid naming collisions
with external names.". This sentence seems to be an implementation detail which
is not necessary to explain (if by internal names we mean e.g. local variables
which are never seen in the object files)?

Finally, it should perhaps be mentioned that this applies only to "F77" names,
as modules, OOP stuff, bind(c), and other modernities are mangled differently
(or for plain bind(C), never mangled), and is not modifiable by these
command-line options.

It should perhaps also be mentioned that bind(C) is a more robust way to create
external symbols with some specific name, rather than playing with compiler
options.