Bug 13756 - [tree-ssa] documentation missing
Summary: [tree-ssa] documentation missing
Status: NEW
Alias: None
Product: gcc
Classification: Unclassified
Component: tree-optimization (show other bugs)
Version: tree-ssa
: P2 normal
Target Milestone: ---
Assignee: Not yet assigned to anyone
Keywords: documentation
Depends on: 951 32965
  Show dependency treegraph
Reported: 2004-01-20 03:26 UTC by Diego Novillo
Modified: 2007-08-02 02:33 UTC (History)
3 users (show)

See Also:
Known to work:
Known to fail:
Last reconfirmed: 2005-12-27 00:38:19


Note You need to log in before you can comment on or make changes to this bug.
Description Diego Novillo 2004-01-20 03:26:31 UTC
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.)
Comment 1 Andrew Pinski 2004-01-20 03:28:51 UTC
Confirmed, there is another PR somewhere about this too.
Comment 2 Diego Novillo 2004-01-20 03:30:07 UTC
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?

Comment 3 Andrew Pinski 2004-01-20 03:31:48 UTC
PR 951 was the one I was thinking of.
Comment 4 Geert Bosch 2004-01-28 01:39:43 UTC
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.

Comment 5 Daniel Berlin 2004-03-15 19:09:21 UTC
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.
Comment 6 Geert Bosch 2004-04-29 19:23:30 UTC
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 

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.

Comment 7 Diego Novillo 2004-05-04 04:01:31 UTC
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.
Comment 8 Joseph S. Myers 2004-05-13 18:56:51 UTC
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

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
Comment 9 Andrew Pinski 2004-05-20 20:12:01 UTC
-ftree-loop-optimize was removed.
Comment 10 Joseph S. Myers 2004-05-30 11:22:27 UTC
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.
Comment 11 Joseph S. Myers 2004-08-13 10:08:34 UTC
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

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

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
Comment 12 Andrew Pinski 2005-01-05 02:10:52 UTC
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
Comment 13 Andrew Pinski 2005-09-27 17:11:10 UTC
There are other non tree-ssa functions which have the same issue.
Comment 14 Rask Ingemann Lambertsen 2007-09-05 19:48:15 UTC
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
	PR web/32965
	PR tree-optimization/13756
	* doc/invoke.texi (Options That Control Optimization): Document