improve comments for doxygen

mpictor · mpictor · commit 89684015ae0e · 2015-05-20T20:03:47.000-04:00
diff --git a/src/base/sc_trace_fprintf.h b/src/base/sc_trace_fprintf.h
@@ -9,17 +9,17 @@
  *
  * This header must be included *after* all other headers, otherwise the compiler will
  * report errors in system headers.
- * \sa trace_fprintf
+ * \sa trace_fprintf()
 **/
 
 #include "sc_export.h"
 
-/** used to find where generated c++ originates from in exp2cxx
- * To enable, configure with 'cmake .. -DSC_TRACE_FPRINTF=ON'
- */
 #ifdef __cplusplus
 extern "C" {
 #endif
+    /** Used to find where generated c++ originates from in exp2cxx.
+     * To enable, configure with 'cmake .. -DSC_TRACE_FPRINTF=ON'
+     */
     SC_BASE_EXPORT void trace_fprintf( char const * sourcefile, int line, FILE * file, const char * format, ... );
 #ifdef __cplusplus
 }
diff --git a/src/clstepcore/STEPattribute.h b/src/clstepcore/STEPattribute.h
@@ -196,8 +196,8 @@ class SC_CORE_EXPORT STEPattribute {
 
 ////////////// Return info on attr
 
-        bool Nullable() const; // may this attribute be null?
-        bool is_null() const;  // is this attribute null?
+        bool Nullable() const; ///< may this attribute be null?
+        bool is_null() const;  ///< is this attribute null?
         bool IsDerived() const  {
             return _derive;
         }
diff --git a/src/exppp/pp.h b/src/exppp/pp.h
@@ -17,13 +17,13 @@ extern FILE * exppp_fp;
 extern bool first_line;
 
 /** output a string, exactly as provided
- * \sa wrap
+ * \sa wrap()
  */
 void raw( const char * fmt, ... );
 
 /** output a string, insert newlines to keep line length down
- * \sa raw
  * TODO list globals this func uses
+ * \sa raw()
  */
 void wrap( const char * fmt, ... );
 
diff --git a/src/exppp/pretty_entity.c b/src/exppp/pretty_entity.c
@@ -1,4 +1,4 @@
-/** \file entity.c
+/** \file pretty_entity.c
  * functions dealing with entities
  * split out of exppp.c 9/21/13
  */
diff --git a/src/exppp/pretty_expr.c b/src/exppp/pretty_expr.c
@@ -1,4 +1,4 @@
-/** \file expr.c
+/** \file pretty_expr.c
  * functions dealing with expressions
  * split out of exppp.c 9/21/13
  */
diff --git a/src/exppp/pretty_rule.c b/src/exppp/pretty_rule.c
@@ -1,4 +1,4 @@
-/** \file rule.c
+/** \file pretty_rule.c
  * split out of exppp.c 9/21/13
  */
 
diff --git a/src/exppp/pretty_scope.c b/src/exppp/pretty_scope.c
@@ -1,4 +1,4 @@
-/** \file scope.c
+/** \file pretty_scope.c
  * split out of exppp.c 9/21/13
  */
 
diff --git a/src/exppp/pretty_subtype.c b/src/exppp/pretty_subtype.c
@@ -1,4 +1,4 @@
-/** \file pp_subtype.c
+/** \file pretty_subtype.c
  * split out of exppp.c 9/21/13
  */
 
diff --git a/src/exppp/pretty_type.c b/src/exppp/pretty_type.c
@@ -1,4 +1,4 @@
-/** \file type.c
+/** \file pretty_type.c
  * split out of exppp.c 9/21/13
  */
 
diff --git a/src/express/dict.c b/src/express/dict.c
@@ -38,8 +38,7 @@
 #include "express/object.h"
 #include "express/expbasic.h"
 
-char DICT_type; /* set as a side-effect of DICT lookup routines */
-/* to type of object found */
+char DICT_type; /**< set to type of object found, as a side-effect of DICT lookup routines */
 
 static Error    ERROR_duplicate_decl;
 static Error    ERROR_duplicate_decl_diff_file;
@@ -122,7 +121,7 @@ int DICTdefine( Dictionary dict, char * name, Generic obj, Symbol * sym, char ty
  * ENUMERATION OF ( A, A ) which has happened!
  * This is the way DICTdefine used to look before enumerations gained
  * their unusual behavior with respect to scoping and visibility rules
- * \sa DICTdefine
+ * \sa DICTdefine()
  */
 int DICT_define( Dictionary dict, char * name, Generic obj, Symbol * sym, char type ) {
     struct Element_ e, *e2;
@@ -181,7 +180,7 @@ Generic DICTlookup( Dictionary dictionary, char * name ) {
 }
 
 /** like DICTlookup but returns symbol, too
- * \sa DICTlookup
+ * \sa DICTlookup()
  */
 Generic DICTlookup_symbol( Dictionary dictionary, char * name, Symbol ** sym ) {
     struct Element_ e, *ep;
diff --git a/src/express/entity.c b/src/express/entity.c
@@ -1,7 +1,8 @@
 
 
-/** **********************************************************************
+/**
 ** Module:  Entity \file entity.c
+*
 ** This module is used to represent Express entity definitions.
 **  An entity definition consists of a name, a set of attributes, a
 **  collection of uniqueness sets, a specification of the entity's
@@ -12,6 +13,7 @@
 **  of the entity.  Thus, the uniqueness set { name, ssn } indicates
 **  that no two instances of the entity may share both the same
 **  values for both name and ssn.
+*
 ** Constants:
 **  ENTITY_NULL - the null entity
 **
@@ -409,9 +411,9 @@ static void ENTITY_get_all_attributes( Entity entity, Linked_List result ) {
  ** \return all attributes of this entity
  **
  ** Retrieve the attribute list of an entity.
- ** \sa ENTITY_get_all_attributes
+ ** \sa ENTITY_get_all_attributes()
  **
- ** Notes:   If an entity has neither defines nor inherits any
+ ** \note   If an entity has neither defines nor inherits any
  **      attributes, this call returns an empty list.  Note
  **      that this is distinct from the constant LIST_NULL.
  */
@@ -428,7 +430,7 @@ Linked_List ENTITYget_all_attributes( Entity entity ) {
 ** \return the named attribute of this entity
 ** Retrieve an entity attribute by name.
 **
-** Notes:   If the entity has no attribute with the given name,
+** \note   If the entity has no attribute with the given name,
 **  VARIABLE_NULL is returned.
 */
 Variable ENTITYget_named_attribute( Entity entity, char * name ) {
@@ -455,7 +457,7 @@ Variable ENTITYget_named_attribute( Entity entity, char * name ) {
 ** \return offset to given attribute
 ** Retrieve offset to an entity attribute.
 **
-** Notes:   If the entity does not include the attribute, -1
+** \note   If the entity does not include the attribute, -1
 **  is returned.
 */
 int ENTITYget_attribute_offset( Entity entity, Variable attribute ) {
@@ -485,7 +487,7 @@ int ENTITYget_attribute_offset( Entity entity, Variable attribute ) {
 ** \return offset to named attribute of this entity
 ** Retrieve offset to an entity attribute by name.
 **
-** Notes:   If the entity has no attribute with the given name,
+** \note   If the entity has no attribute with the given name,
 **      -1 is returned.
 */
 int ENTITYget_named_attribute_offset( Entity entity, char * name ) {
diff --git a/src/express/expr.c b/src/express/expr.c
@@ -852,8 +852,8 @@ Type EXPresolve_op_unary_minus( Expression e, Scope s ) {
 }
 
 /** Initialize one entry in EXPop_table
- * This table's function pointers are resolved in \sa EXP_resolve()
- * , at approx resolve.c:520
+ * This table's function pointers are resolved in EXP_resolve(), at approx resolve.c:520
+ * \sa EXP_resolve()
  * \sa EXPop_init()
  *
  * \param token_number operator value, usually in macro form
diff --git a/src/express/express.c b/src/express/express.c
@@ -1,6 +1,6 @@
 
 
-/** **********************************************************************
+/**
 ** \file express.c
 ** Express package manager.
 ************************************************************************/
@@ -682,6 +682,7 @@ Schema EXPRESSfind_schema( Dictionary modeldict, char * name ) {
  * make the initial connections from one schema to another
  * dictated by USE/REF clauses that use dictionaries, i.e.,
  * because of partial schema references
+ * \sa connect_schema_lists()
  */
 static void connect_lists( Dictionary modeldict, Schema schema, Linked_List list ) {
     Rename * r;
@@ -702,7 +703,7 @@ static void connect_lists( Dictionary modeldict, Schema schema, Linked_List list
 
 /**
  * same as `connect_lists` except for full schemas
- * \sa connect_lists
+ * \sa connect_lists()
  */
 static void connect_schema_lists( Dictionary modeldict, Schema schema, Linked_List schema_list ) {
     Symbol * sym;
diff --git a/src/express/scope.c b/src/express/scope.c
@@ -1,15 +1,16 @@
 
 
-/** **********************************************************************
-** Module:  Scope \file scope.c
-** This module implements a hierarchical (i.e., scoped)
-**  symbol table.  The symbol table can store definitions of entities,
-**  types, algorithms, and variables, as well as containing a list
-**  of subscopes.
-** Constants:
-**  SCOPE_NULL  - the null scope
-**
-************************************************************************/
+/**
+ * Module:  Scope \file scope.c
+ *
+ *  This module implements a hierarchical (i.e., scoped)
+ *  symbol table.  The symbol table can store definitions of entities,
+ *  types, algorithms, and variables, as well as containing a list
+ *  of subscopes.
+ *
+ * Constants:
+ *  SCOPE_NULL  - the null scope
+ */
 
 /*
  * This software was developed by U.S. Government employees as part of
@@ -52,8 +53,8 @@ void SCOPEinitialize( void ) {
     MEMinitialize( &SCOPE_fl, sizeof( struct Scope_ ), 100, 50 );
 }
 
-/**  SCOPE_get_entities
- * \sa SCOPEget_entities
+/**
+ * \sa SCOPEget_entities()
  */
 void SCOPE_get_entities( Scope scope, Linked_List result ) {
     DictionaryEntry de;
@@ -65,8 +66,8 @@ void SCOPE_get_entities( Scope scope, Linked_List result ) {
     }
 }
 
-/**  SCOPE_get_functions
- * \sa SCOPEget_functions
+/**
+ * \sa SCOPEget_functions()
  */
 void SCOPE_get_functions( Scope scope, Linked_List result ) {
     DictionaryEntry de;
@@ -77,17 +78,17 @@ void SCOPE_get_functions( Scope scope, Linked_List result ) {
         LISTadd_last( result, x );
     }
 }
-/**  SCOPE_get_functions
- * \sa SCOPEget_functions
+/**
+ * \sa SCOPE_get_functions()
  */
 Linked_List SCOPEget_functions( Scope scope ) {
     Linked_List result = LISTcreate();
     SCOPE_get_functions( scope, result );
     return( result );
 }
 
-/**  SCOPE_get_rules
- * \sa SCOPEget_rules
+/**
+ * \sa SCOPEget_rules()
  */
 void SCOPE_get_rules( Scope scope, Linked_List result ) {
     DictionaryEntry de;
@@ -98,8 +99,8 @@ void SCOPE_get_rules( Scope scope, Linked_List result ) {
         LISTadd_last( result, x );
     }
 }
-/**  SCOPE_get_functions
- * \sa SCOPEget_functions
+/**
+ * \sa SCOPE_get_rules()
  */
 Linked_List SCOPEget_rules( Scope scope ) {
     Linked_List result = LISTcreate();
@@ -125,7 +126,7 @@ Linked_List SCOPEget_entities( Scope scope ) {
 }
 
 /**
- * \sa SCOPEget_entities_superclass_order
+ * \sa SCOPEget_entities_superclass_order()
  */
 void SCOPE_dfs( Dictionary symbols, Entity root, Linked_List result ) {
     Entity ent;
@@ -150,7 +151,7 @@ void SCOPE_dfs( Dictionary symbols, Entity root, Linked_List result ) {
  ** Retrieve a list of the entities defined locally in a scope.
  **
  ** \note The list returned is ordered such that an entity appears before all of its subtypes.
- ** \sa SCOPEget_entities
+ ** \sa SCOPEget_entities()
  */
 Linked_List SCOPEget_entities_superclass_order( Scope scope ) {
     Linked_List result;

Original file line number	Diff line number	Diff line change
`@@ -196,8 +196,8 @@ class SC_CORE_EXPORT STEPattribute {`
`196`	`196`
`197`	`197`	`////////////// Return info on attr`
`198`	`198`
`199`		`- bool Nullable() const; // may this attribute be null?`
`200`		`- bool is_null() const; // is this attribute null?`
	`199`	`+ bool Nullable() const; ///< may this attribute be null?`
	`200`	`+ bool is_null() const; ///< is this attribute null?`
`201`	`201`	`bool IsDerived() const {`
`202`	`202`	`return _derive;`
`203`	`203`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/** \file entity.c`
	`1`	`+/** \file pretty_entity.c`
`2`	`2`	`* functions dealing with entities`
`3`	`3`	`* split out of exppp.c 9/21/13`
`4`	`4`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/** \file expr.c`
	`1`	`+/** \file pretty_expr.c`
`2`	`2`	`* functions dealing with expressions`
`3`	`3`	`* split out of exppp.c 9/21/13`
`4`	`4`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/** \file rule.c`
	`1`	`+/** \file pretty_rule.c`
`2`	`2`	`* split out of exppp.c 9/21/13`
`3`	`3`	`*/`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/** \file scope.c`
	`1`	`+/** \file pretty_scope.c`
`2`	`2`	`* split out of exppp.c 9/21/13`
`3`	`3`	`*/`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/** \file pp_subtype.c`
	`1`	`+/** \file pretty_subtype.c`
`2`	`2`	`* split out of exppp.c 9/21/13`
`3`	`3`	`*/`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-/** \file type.c`
	`1`	`+/** \file pretty_type.c`
`2`	`2`	`* split out of exppp.c 9/21/13`
`3`	`3`	`*/`
`4`	`4`