[Bug other/13756] New: tree-ssa documentation missing in the internals manual

[Bug other/13756] New: tree-ssa documentation missing in the internals manual

[dnovillo at gcc dot gnu dot org]

From: 	Joseph S. Myers

The internals manual is where what documentation there is of the front
endinterface (with some documentation of trees) presently is and where
thingsshould link into.  It isn't presently wonderfully coherent in structurebut
given the documentation written in some chapters of the manual, theycan always
be reordered later as necessary to give a better-definedstructure.  (My old
outline of a possible structure for the front-endinterface parts of the
internals manual is at<http://gcc.gnu.org/ml/gcc/2001-06/msg00125.html>.  I
wrote a few bits ofthis for sourcebuild.texi but the bulk of the front-end
interface isundocumented.  I'm not asking for you to write all of this, just
todocument all the new and different front-end interfaces on tree-ssa.)

-- 
           Summary: tree-ssa documentation missing in the internals manual
           Product: gcc
           Version: tree-ssa
            Status: UNCONFIRMED
          Severity: normal
          Priority: P2
         Component: other
        AssignedTo: dnovillo at gcc dot gnu dot org
        ReportedBy: dnovillo at gcc dot gnu dot org
                CC: gcc-bugs at gcc dot gnu dot org


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

[Bug other/13756] [tree-ssa] documentation missing in the internals manual

[pinskia at gcc dot gnu dot org]

------- Additional Comments From pinskia at gcc dot gnu dot org  2004-01-20 03:28 -------
Confirmed, there is another PR somewhere about this too.

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |ASSIGNED
     Ever Confirmed|                            |1
           Keywords|                            |documentation
   Last reconfirmed|0000-00-00 00:00:00         |2004-01-20 03:28:51
               date|                            |
            Summary|tree-ssa documentation      |[tree-ssa] documentation
                   |missing in the internals    |missing in the internals
                   |manual                      |manual
   Target Milestone|---                         |tree-ssa


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

[Bug other/13756] [tree-ssa] documentation missing in the internals manual

[dnovillo at redhat dot com]

------- Additional Comments From dnovillo at redhat dot com  2004-01-20 03:30 -------
Subject: Re:  [tree-ssa] documentation missing in the
	internals manual

On Mon, 2004-01-19 at 22:28, pinskia at gcc dot gnu dot org wrote:
> ------- Additional Comments From pinskia at gcc dot gnu dot org  2004-01-20 03:28 -------
> Confirmed, there is another PR somewhere about this too.
>
Can they be linked somehow?



-- 


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

[Bug other/13756] [tree-ssa] documentation missing in the internals manual

[pinskia at gcc dot gnu dot org]

------- Additional Comments From pinskia at gcc dot gnu dot org  2004-01-20 03:31 -------
PR 951 was the one I was thinking of.

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
  BugsThisDependsOn|                            |951


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

[Bug other/13756] [tree-ssa] documentation missing in the internals manual

[bosch at gcc dot gnu dot org]

------- Additional Comments From bosch at gcc dot gnu dot org  2004-01-28 01:39 -------
There is no global overview of tree-ssa. The "main page" of the
documentation is empty, and there is no single place that describes
what tree-ssa is and what the overall structure is.

The most useful piece of high-level info is in the proceedings of
the 2003 GCC Summit, page 171-195, but I agree with Richard Kenner that
most of this information should be contained in the various files that
make up tree-ssa.

Unfortunately, the referenced information is in PDF format, so I cannot
easily cut and paste some of it to illustrate my point.

   -Geert


-- 


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

[Bug other/13756] [tree-ssa] documentation missing in the internals manual

[dberlin at gcc dot gnu dot org]

------- Additional Comments From dberlin at gcc dot gnu dot org  2004-03-15 19:09 -------
Documentation for -ftree-loop-optimize, as well as the switch itself, needs to be removed from the 
branch before merge.
The switch only has meaning on the lno-branch.
The switch + docs was added, then it was decided that the loop stuff should go to lno-branch, and 
nobody removed the switch again.

-- 


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

[Bug other/13756] [tree-ssa] documentation missing in the internals manual

[bosch at gcc dot gnu dot org]

------- Additional Comments From bosch at gcc dot gnu dot org  2004-04-29 19:23 -------
Here are additional comments after reading the GCC Internals manual from the tree-ssa branch. 
Although Chapter 7 describes the high-level process of going from language-specific trees to GENERIC, 
then lowering to GIMPLE and finally going through the various SSA and non-SSA passes
is described in sufficient detail, there is no information on the GENERIC and GIMPLE representations 
themselves.

Chapter 8 describes C and C++ front end specific trees, but there is a complete disconnect with tree-
ssa. This chapter needs to be changed to reflect the situation in the tree-ssa branch.

Chapter 9, which deals with analysis and optimization of GIMPLE trees starts with a small introduction 
that refers to "the chapter describing GENERIC and GIMPLE" for more details. Such a chapter is much 
needed, especially since one of the stated goals of tree-ssa is to improve maintainability.

  -Geert

-- 


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

[Bug other/13756] [tree-ssa] documentation missing in the internals manual

[dnovillo at gcc dot gnu dot org]

------- Additional Comments From dnovillo at gcc dot gnu dot org  2004-05-04 04:01 -------

jason added GENERIC and GIMPLE documentation recently.  I don't see a ChangeLog
entry for it, though.  That seems to be the last major piece of missing
documentation in the branch.

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|ASSIGNED                    |WAITING


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[jsm28 at gcc dot gnu dot org]

------- Additional Comments From jsm28 at gcc dot gnu dot org  2004-05-13 18:56 -------
tree-ssa documentation still missing after the mainline merge:

The autoconf and automake versions for the new libbanshee, libgfortran
and libmudflap directories aren't documented in install.texi, but
aren't all the defaults given there for unlisted directories either.
Some also add new versions that weren't previously in the list of those
used.

The new configure options --enable-tree-browser and --with-libbanshee
aren't documented in install.texi.

The options -ftree-combine-temps -ftree-dse -ftree-loop-optimize
-ftree-points-to aren't documented in invoke.texi.  Other -ftree-*
options are documented but without use of @opindex to create index
entries.


-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jsm28 at gcc dot gnu dot org
             Status|WAITING                     |NEW
   Last reconfirmed|2004-03-07 09:29:23         |2004-05-13 18:56:52
               date|                            |
            Summary|[tree-ssa] documentation    |[tree-ssa] documentation
                   |missing in the internals    |missing
                   |manual                      |


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[pinskia at gcc dot gnu dot org]

------- Additional Comments From pinskia at gcc dot gnu dot org  2004-05-20 20:12 -------
-ftree-loop-optimize was removed.

-- 


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[jsm28 at gcc dot gnu dot org]

------- Additional Comments From jsm28 at gcc dot gnu dot org  2004-05-30 11:22 -------
libgfortran also has an undocumented --enable-cmath configure option.
All configure options should be documented in install.texi; a poor
second-best save maybe for options only of use to GCC developers
is linking from there to separate documentation of a library's options.


-- 


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[jsm28 at gcc dot gnu dot org]

------- Additional Comments From jsm28 at gcc dot gnu dot org  2004-08-13 10:08 -------
Functions without comments above them:

gimple-low.c: lower_return_expr

gimplify.c: gimple_push_bind_expr gimple_pop_bind_expr gimple_current_bind_expr
get_formal_tmp_var gimple_add_tmp_var annotate_one_with_locus
annotate_all_with_locus unmark_visited_r gimplify_case_label_expr
shortcut_cond_expr

tree-alias-ander.c: get_ref pta_make_lam print_out_result

tree-alias-common.c: alias_get_name

tree-alias-type.c: alias_var_new_with_aterm

tree-browser.c: TB_current_chain_node

tree-cfg.c: execute_build_cfg remove_useless_stmts_cond remove_useless_stmts_tf
remove_useless_stmts_tc remove_useless_stmts_bind remove_useless_stmts_goto
remove_useless_stmts_label remove_useless_stmts_1 remove_useless_stmts
compute_dominance_frontiers tree_purge_dead_eh_edges
tree_purge_all_dead_eh_edges

Many more files not checked, but you get the idea.  All functions must
have comments above them describing what the function does, all its
parameters, and its return value if any.  A reasonable approximation to
a list of undocumented functions in a file can be obtained with

perl -ne 'if (/^\/\*/) { $sc = 1; }; if (/^}\n$/) { $sc = 0; }; if (/^[a-z]/ &&
!$sc) { print $_; }' <source-file.c

-- 


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[pinskia at gcc dot gnu dot org]

------- Additional Comments From pinskia at gcc dot gnu dot org  2005-01-05 02:10 -------
Note the following were removed:
tree-alias-ander.c: get_ref pta_make_lam print_out_result
tree-alias-common.c: alias_get_name
tree-alias-type.c: alias_var_new_with_aterm

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
   Last reconfirmed|2004-05-13 18:56:52         |2005-01-05 02:10:52
               date|                            |


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[mmitchel at gcc dot gnu dot org]

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
   Target Milestone|4.0.0                       |4.0.1


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[mmitchel at gcc dot gnu dot org]

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
   Target Milestone|4.0.1                       |4.0.2


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[pinskia at gcc dot gnu dot org]

------- Additional Comments From pinskia at gcc dot gnu dot org  2005-09-27 17:11 -------
There are other non tree-ssa functions which have the same issue.

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
   Target Milestone|4.0.2                       |4.0.3


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[egallager at gcc dot gnu.org]

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

Eric Gallager <egallager at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |patch
                URL|                            |https://gcc.gnu.org/piperma
                   |                            |il/gcc-patches/2024-March/6
                   |                            |48306.html

--- Comment #19 from Eric Gallager <egallager at gcc dot gnu.org> ---
Patch posted: https://gcc.gnu.org/pipermail/gcc-patches/2024-March/648306.html

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[pinskia at gcc dot gnu.org]

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

--- Comment #18 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Note libmudflap was removed back in 2014.

libgfortran is still there though.
Someone has to audit the comments here to figure out if there is anything else
to be done.

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[rask at gcc dot gnu dot org]

------- Comment #14 from rask at gcc dot gnu dot org  2007-09-05 19:48 -------
Subject: Bug 13756

Author: rask
Date: Wed Sep  5 19:47:56 2007
New Revision: 128146

URL: http://gcc.gnu.org/viewcvs?root=gcc&view=rev&rev=128146
Log:
        PR web/32965
        PR tree-optimization/13756
        * doc/invoke.texi (Options That Control Optimization): Document
        -ftree-dse.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/doc/invoke.texi


-- 


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

[Bug tree-optimization/13756] [tree-ssa] documentation missing

[pinskia at gcc dot gnu dot org]

-- 

pinskia at gcc dot gnu dot org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
   Last reconfirmed|2005-07-01 22:13:20         |2005-12-27 00:38:19
               date|                            |
   Target Milestone|4.0.3                       |---


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