[Bug fortran/78377] New: [cleanup] gfc_get_tbp_symtree vs. gfc_get_sym_tree

[janus at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=78377

            Bug ID: 78377
           Summary: [cleanup] gfc_get_tbp_symtree vs. gfc_get_sym_tree
           Product: gcc
           Version: 7.0
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: fortran
          Assignee: unassigned at gcc dot gnu.org
          Reporter: janus at gcc dot gnu.org
  Target Milestone: ---

This PR does not concern an actual bug, but is merely meant to track a cleanup
issue in the gfortran source code (related to naming and documentation etc). In
some sense it is a follow-up to PR 77501, where the issue was brought up, see
https://gcc.gnu.org/ml/fortran/2016-11/msg00100.html.

The issue essentially concerns this function in class.c:


gfc_symtree*
gfc_get_tbp_symtree (gfc_symtree **root, const char *name)
{
  gfc_symtree *result = gfc_find_symtree (*root, name);
  return result ? result : gfc_new_symtree (root, name);
}


Here is a list of possible things to do:

1) Rename the function, removing 'tbp' from the name, since nothing about it is
specific to type-bound procedures any more (as noted by Mikael).

2) Move the function into symbol.c, preferably close to other related functions
like:
* gfc_find_symtree
* gfc_new_symtree
* gfc_get_sym_tree

3) In addition to picking a proper name, one should improve the documentation
of these functions, including a clarification of their relations and use cases.

4) In particular the relation of gfc_get_tbp_symtree and gfc_get_sym_tree
should be made clear. Both essentially rely on a combination of
gfc_find_symtree and gfc_new_symtree (the latter does much more than the
former, though). When is it ok to use the first one? When should one use the
second? Also the relation to 'gfc_get_ha_sym_tree' could be clarified.

5) There are similar problems with gfc_find_sym_tree vs. gfc_find_symtree (and
gfc_find_symtree_in_proc). They can be easily confused by name (in particular
the first two), and their relation is not properly documented.