Document purpose of each ld statement lists

When discovering the statement lists via their header variable
statement_list, file_chain and input_file_chain it can be confusing to
figure out what they are for. They can point to the same initial
statement and the relation between the next field they use is not
obvious from the name.

This commit adds comment for each of those statement list header to
explain what they are for and what next field they use. It also rewrite
the comment for the next fields to simply redirect the reader to the
list header to avoid duplication of documentation.

2018-11-29  Thomas Preud'homme  <thomas.preudhomme@linaro.org>

ld/
	* ldlang.c (statement_list): Document purpose and what next field it
	uses.
	(file_chain): Likewise.
	(input_file_chain): Likewise.
	* ldlang.h (lang_statement_header_type): Document statement list header
	the next pointer correspond to.
	(lang_statement_header_type): Replace comment for next and
	next_real_file field to refer the reader to their corresponding
	statement list header.

1 files changed, 3 insertions, 7 deletions

diff --git a/ld/ldlang.h b/ld/ldlang.h
index dfac0b1b68e..325bbbb5242 100644
--- a/ld/ldlang.h
+++ b/ld/ldlang.h
@@ -88,6 +88,7 @@ enum statement_enum
 
 typedef struct lang_statement_header_struct
 {
+  /* Next pointer for statement_list statement list.  */
   union lang_statement_union *next;
   enum statement_enum type;
 } lang_statement_header_type;
@@ -306,15 +307,10 @@ typedef struct lang_input_statement_struct
 
   struct flag_info *section_flag_list;
 
-  /* Point to the next file - whatever it is, wanders up and down
-     archive elements.  If this input_statement is for an archive, it
-     won't be on file_chain (which uses this list pointer), but if
-     any elements have been extracted from the archive, it will point
-     to the input_statement for the last such element.  */
+  /* Next pointer for file_chain statement list.  */
   union lang_statement_union *next;
 
-  /* Point to the next file, but skips archive contents.  Used by
-     input_file_chain.  */
+  /* Next pointer for input_file_chain statement list.  */
   union lang_statement_union *next_real_file;
 
   const char *target;