Merge pull request #791 from owen-jones-diffblue/doc/symbol-table

Document symbol table functions

Author: Daniel Kroening

src/util/symbol_table.cpp

@@ -14,11 +14,14 @@ Author: Daniel Kroening, [email protected]
 
 Function: symbol_tablet::add
 
-  Inputs:
+ Inputs:
+  symbol - The symbol to be added to the symbol table
 
- Outputs:
+ Outputs: Returns a boolean indicating whether the process failed,
+          which should only happen if there is a symbol with the same
+          name already in the symbol table
 
- Purpose:
+ Purpose: Add a new symbol to the symbol table
 
 \*******************************************************************/
 
@@ -39,11 +42,28 @@ bool symbol_tablet::add(const symbolt &symbol)
 
 Function: symbol_tablet::move
 
-  Inputs:
-
- Outputs:
-
- Purpose:
+ Inputs:
+  symbol - The symbol to be added to the symbol table
+  new_symbol - Pointer which the function will set to either point
+               to the symbol in the symbol table with the same name
+               or to the symbol that has been successfully moved
+               into the symbol table
+
+ Outputs: Returns a boolean indicating whether the process failed,
+          which should only happen if there is a symbol with the
+          same name already in the symbol table. If the process
+          failed then symbol is unchanged and new_symbol points to
+          the symbol with the same name. If the process succeeded
+          symbol is set to be empty and new_symbol points to its new
+          location in the symbol table
+
+ Purpose: Move a symbol into the symbol table. If there is already
+          a symbol with the same name then symbol is unchanged,
+          new_symbol points to the symbol with the same name and
+          true is returned. Otherwise, the symbol is moved into the
+          symbol table, symbol is set to be empty, new_symbol points
+          to its new location in the symbol table and false is
+          returned
 
 \*******************************************************************/
 
@@ -75,11 +95,12 @@ bool symbol_tablet::move(symbolt &symbol, symbolt *&new_symbol)
 
 Function: symbol_tablet::remove
 
-  Inputs:
+ Inputs:
+  name - The name of the symbol to remove
 
- Outputs:
+ Outputs: Returns a boolean indicating whether the process failed
 
- Purpose:
+ Purpose: Remove a symbol from the symbol table
 
 \*******************************************************************/
 
@@ -121,11 +142,12 @@ bool symbol_tablet::remove(const irep_idt &name)
 
 Function: symbol_tablet::show
 
-  Inputs:
+ Inputs:
+  out - The ostream to direct output to
 
  Outputs:
 
- Purpose:
+ Purpose: Print the contents of the symbol table
 
 \*******************************************************************/
 
@@ -141,11 +163,13 @@ void symbol_tablet::show(std::ostream &out) const
 
 Function: symbol_tablet::lookup
 
-  Inputs:
+ Inputs:
+  identifier - The name of the symbol to look for
 
- Outputs:
+ Outputs: The symbol in the symbol table with the correct name
 
- Purpose:
+ Purpose: Find a symbol in the symbol table. Throws a string if no
+          such symbol is found.
 
 \*******************************************************************/
 
@@ -163,11 +187,13 @@ const symbolt &symbol_tablet::lookup(const irep_idt &identifier) const
 
 Function: symbol_tablet::lookup
 
-  Inputs:
+ Inputs:
+  identifier - The name of the symbol to look for
 
- Outputs:
+ Outputs: The symbol in the symbol table with the correct name
 
- Purpose:
+ Purpose: Find a symbol in the symbol table. Throws a string if no
+          such symbol is found.
 
 \*******************************************************************/
 
@@ -185,11 +211,13 @@ symbolt &symbol_tablet::lookup(const irep_idt &identifier)
 
 Function: operator <<
 
-  Inputs:
+ Inputs:
+  out - The ostream to direct output to
+  symbol_table - The symbol table to print out
 
  Outputs:
 
- Purpose:
+ Purpose: Print the contents of the symbol table
 
 \*******************************************************************/