[PATCH, Fortran] PING: Extend gfc_code internal documentation

[Daniel Kraft <domob1812 at gmail dot com>]

Daniel Kraft wrote:
> this patch extends the documentation of the gfc_code structure in the 
> gfc-internals.texi documentation.  It adds an example about how the 
> block-chaining for IF/SELECT works and has three detail subsections 
> about DO, IF and SELECT blocks.

Are there any comments on that one?  Otherwise I'll check it in on 
Saturday evening without the XXX comments, as discussed with FX.

Thanks,
Daniel

> Please give it a close look as I'm myself rather unsure about the things 
> I wrote about...  And there are two XXX marks in, please comment on 
> those, too.  Otherwise I think it should be faily simple and if it's ok 
> I'll check it in.  Then I can start writing a bit about gfc_expr in a 
> new following section.
>
> Daniel


--
Done:     Bar-Sam-Val-Wiz, Dwa-Elf-Hum-Orc, Cha-Law, Fem-Mal
Underway: Ran-Gno-Neu-Fem
To go:    Arc-Cav-Hea-Kni-Mon-Pri-Rog-Tou

2008-06-22  Daniel Kraft  <d@domob.eu>

	* gfc-internals.texi (section gfc_code):  Extended documentation about
	gfc_code in the internal datastructures chapter including details about
	how IF, DO and SELECT blocks look like and an example for how the
	block-chaining works.

Index: gcc/fortran/gfc-internals.texi
===================================================================
--- gcc/fortran/gfc-internals.texi	(revision 136954)
+++ gcc/fortran/gfc-internals.texi	(working copy)
@@ -284,9 +284,12 @@ should exhaust all possible valid combin
 structures.
 
 @menu
-* gfc_code:: Representation of Executable Statements
+* gfc_code:: Representation of Executable Statements.
 @end menu
 
+@c gfc_code
+@c --------
+
 @node gfc_code
 @section @code{gfc_code}
 @cindex statement chaining
@@ -309,13 +312,94 @@ current statement.
 If the current statement is one of @code{IF}, @code{DO}, @code{SELECT}
 it starts a block, i.e.@: a nested level in the program.  In order to
 represent this, the @code{block} member is set to point to a
-@code{gfc_code} structure whose @code{block} member points to the
-block in question.  The @code{SELECT} and @code{IF} statements may
-contain various blocks (the chain of @code{ELSE IF} and @code{ELSE}
-blocks or the various @code{CASE}s, respectively).
-
-@c What would be nice here would be an example program together with
-@c an image that says more than the mythical thousand words.
+@code{gfc_code} structure whose @code{next} member starts the chain of
+statements inside the block; this structure's @code{op} member should be set to
+the same value as the parent structure's @code{op} member.  The @code{SELECT}
+and @code{IF} statements may contain various blocks (the chain of @code{ELSE IF}
+and @code{ELSE} blocks or the various @code{CASE}s, respectively).  These chains
+are linked-lists formed by the @code{block} members.
+
+Consider the following example code:
+
+@example
+IF (foo < 20) THEN
+  PRINT *, "Too small"
+  foo = 20
+ELSEIF (foo > 50) THEN
+  PRINT *, "Too large"
+  foo = 50
+ELSE
+  PRINT *, "Good"
+END IF
+@end example
+
+This statement-block will be represented in the internal gfortran tree like
+this, were the horizontal link-chains are those induced by the @code{next}
+members and vertical links down are those of @code{block}. @samp{==|} and
+@samp{--|} mean @code{NULL} pointers to mark the end of a chain:
+
+@c XXX: Decide on right format for this "image".
+@example
+... ==> IF ==> ...
+        |
+        +--> IF foo < 20 ==> PRINT *, "Too small" ==> foo = 20 ==|
+             |
+             +--> IF foo > 50 ==> PRINT *, "Too large" ==> foo = 50 ==|
+                  |
+                  +--> ELSE ==> PRINT *, "Good" ==|
+                       |
+                       +--|
+@end example
+
+@c XXX: Make those seperate nodes?
+@subsection IF Blocks
+
+Conditionals are represented by @code{gfc_code} structures with their
+@code{op} member set to @code{EXEC_IF}.  This structure's @code{block}
+member must point to another @code{gfc_code} node being the header of the
+if-block.  This header's @code{op} member must be set to @code{EXEC_IF}, too,
+its @code{expr} member holds the condition to check for, and its @code{next}
+should point to the code-chain of the statements to execute if the condition is
+true.
+
+If in addition an @code{ELSEIF} or @code{ELSE} block is present, the
+@code{block} member of the if-block-header node points to yet another
+@code{gfc_code} structure that is the header of the elseif- or else-block.  Its
+structure is identical to that of the if-block-header, except that in case of an
+@code{ELSE} block without a new condition the @code{expr} member should be
+@code{NULL}.  This block can itself have its @code{block} member point to the
+next @code{ELSEIF} or @code{ELSE} block if there's a chain of them.
+
+@subsection Loops
+
+@code{DO} loops are stored in the tree as @code{gfc_code} nodes with their
+@code{op} set to @code{EXEC_DO} for a @code{DO} loop with iterator variable and
+to @code{EXEC_DO_WHILE} for infinite @code{DO}s and @code{DO WHILE} blocks.
+Their @code{block} member should point to a @code{gfc_code} structure heading
+the code-chain of the loop body; its @code{op} member should be set to
+@code{EXEC_DO} or @code{EXEC_DO_WHILE}, too, respectively.
+
+For @code{DO WHILE} loops, the loop condition is stored on the top
+@code{gfc_code} structure's @code{expr} member; @code{DO} forever loops are
+simply @code{DO WHILE} loops with a constant @code{.TRUE.} loop condition in
+the internal representation.
+
+Similarly, @code{DO} loops with an iterator have instead of the condition their
+@code{ext.iterator} member set to the correct values for the loop iterator
+variable and its range.
+
+@subsection @code{SELECT} Statements
+
+A @code{SELECT} block is introduced by a @code{gfc_code} structure with an
+@code{op} member of @code{EXEC_SELECT} and @code{expr} containing the expression
+to evaluate and test.  Its @code{block} member starts a list of @code{gfc_code}
+structures linked together by their @code{block} members that stores the various
+@code{CASE} parts.
+
+Each @code{CASE} node has its @code{op} member set to @code{EXEC_SELECT}, too,
+its @code{next} member points to the code-chain to be executed in the current
+case-block, and @code{extx.case_list} contains the case-values this block
+corresponds to.  The @code{block} member links to the next case in the list.
 
 
 @c ---------------------------------------------------------------------