[7/7] Refresh getter/setter comments.
Commit Message
In a previous change, some useful field documentation was lost when
default constructors were removed. This patch incorporates the useful
bits into getter/setter comments, fixes some minor omissions and adds
some clarifications.
This is a document comment change only.
Signed-off-by: Giuliano Procida <gprocida@google.com>
---
src/abg-suppression.cc | 67 +++++++++++++++++++++++++++---------------
1 file changed, 44 insertions(+), 23 deletions(-)
@@ -133,7 +133,11 @@ suppression_base::get_label() const
/// Setter for the label associated to this suppression specification.
///
-/// @param label the new label.
+/// @param label the new label. This is intended to be an informative
+/// text string that the evalution code might use to designate this
+/// function suppression specification in error messages. This
+/// parameter might be empty, in which case it's ignored at evaluation
+/// time.
void
suppression_base::set_label(const string& label)
{priv_->label_ = label;}
@@ -142,10 +146,11 @@ suppression_base::set_label(const string& label)
/// of @ref suppression_base.
///
/// The "file_name_regex" property is a regular expression string that
-/// designates the file name that contains the ABI artifact this
-/// suppression should apply to.
+/// identifies files containing ABI artifacts that this suppression
+/// should apply to.
///
-/// @param regexp the new regular expression string.
+/// @param regexp the new regular expression string that denotes the
+/// file names to match.
void
suppression_base::set_file_name_regex_str(const string& regexp)
{priv_->file_name_regex_str_ = regexp;}
@@ -154,8 +159,8 @@ suppression_base::set_file_name_regex_str(const string& regexp)
/// of @ref suppression_base.
///
/// The "file_name_regex" property is a regular expression string that
-/// designates the file name that contains the ABI artifacts this
-/// suppression should apply to.
+/// identifies files containing ABI artifacts that this suppression
+/// should apply to.
///
/// @return the regular expression string.
const string&
@@ -165,12 +170,12 @@ suppression_base::get_file_name_regex_str() const
/// Setter for the "file_name_not_regex" property of the current
/// instance of @ref suppression_base.
///
-/// The current suppression specification should apply to ABI
-/// artifacts of a file which name does *NOT* match the regular
-/// expression string designated by the "file_name_not_regex"
-/// property.
+/// The "file_name_not_regex" property is a regular expression string
+/// that identifies files containing ABI artifacts that this
+/// suppression should *NOT* apply to.
///
-/// @param regexp the new regular expression string.
+/// @param regexp the new regular expression string that denotes the
+/// file names to *NOT* match.
void
suppression_base::set_file_name_not_regex_str(const string& regexp)
{priv_->file_name_not_regex_str_ = regexp;}
@@ -178,10 +183,9 @@ suppression_base::set_file_name_not_regex_str(const string& regexp)
/// Getter for the "file_name_not_regex" property of the current
/// instance of @ref suppression_base.
///
-/// The current suppression specification should apply to ABI
-/// artifacts of a file which name does *NOT* match the regular
-/// expression string designated by the "file_name_not_regex"
-/// property.
+/// The "file_name_not_regex" property is a regular expression string
+/// that identifies files containing ABI artifacts that this
+/// suppression should *NOT* apply to.
///
/// @return the regular expression string.
const string&
@@ -471,7 +475,7 @@ type_suppression::get_type_name_regex_str() const
/// This returns a regular expression string that specifies the family
/// of types that should be kept after suppression.
///
-/// @param r the new regexp string.
+/// @param r the new regular expression.
void
type_suppression::set_type_name_not_regex_str(const string& r)
{priv_->set_type_name_not_regex_str(r);}
@@ -482,7 +486,7 @@ type_suppression::set_type_name_not_regex_str(const string& r)
/// This returns a regular expression string that specifies the family
/// of types that should be kept after suppression.
///
-/// @return the new regexp string.
+/// @return the new regular expression string.
const string&
type_suppression::get_type_name_not_regex_str() const
{return priv_->get_type_name_not_regex_str();}
@@ -1926,14 +1930,15 @@ read_type_suppression(const ini::config::section& section,
/// Constructor for the @ref the function_suppression::parameter_spec
/// type.
///
+/// Note that at evaluation time, the parameter @tn_regex is taken
+/// into account only if the parameter @p tn is empty.
+///
/// @param i the index of the parameter designated by this specification.
///
/// @param tn the type name of the parameter designated by this specification.
///
/// @param tn_regex a regular expression that defines a set of type
-/// names for the parameter designated by this specification. Note
-/// that at evaluation time, this regular expression is taken in
-/// account only if the parameter @p tn is empty.
+/// names for the parameter designated by this specification.
function_suppression::parameter_spec::parameter_spec(size_t i,
const string& tn,
const string& tn_regex)
@@ -2069,6 +2074,10 @@ function_suppression::set_name(const string& n)
/// Getter for a regular expression for a family of names of functions
/// the user wants the current specification to designate.
///
+/// If the name as returned by function_suppression::get_name() is not
+/// empty, then this property is ignored at specification evaluation
+/// time.
+///
/// @return the regular expression for the possible names of the
/// function(s).
const string&
@@ -2078,6 +2087,10 @@ function_suppression::get_name_regex_str() const
/// Setter for a regular expression for a family of names of functions
/// the user wants the current specification to designate.
///
+/// If the name as returned by function_suppression::get_name() is not
+/// empty, then this property is ignored at specification evaluation
+/// time.
+///
/// @param r the new the regular expression for the possible names of
/// the function(s).
void
@@ -3355,6 +3368,7 @@ variable_suppression::set_name(const string& n)
/// Getter for the regular expression for a family of names of
/// variables the user wants the current specification to designate.
+///
/// If the variable name as returned by
/// variable_suppression::get_name() is not empty, then this property
/// is ignored at evaluation time. This property might be empty, in
@@ -3367,6 +3381,7 @@ variable_suppression::get_name_regex_str() const
/// Setter for the regular expression for a family of names of
/// variables the user wants the current specification to designate.
+///
/// If the variable name as returned by
/// variable_suppression::get_name() is not empty, then this property
/// is ignored at evaluation time. This property might be empty, in
@@ -3386,7 +3401,7 @@ variable_suppression::get_name_not_regex_str() const
/// Setter for the "name_not_regexp" property of the specification.
///
-/// @param r the new value of the "name_not_regexp" property.
+/// @param r the new regular expression for variable name exclusion.
void
variable_suppression::set_name_not_regex_str(const string& r)
{priv_->name_not_regex_str_ = r;}
@@ -3498,7 +3513,10 @@ variable_suppression::set_symbol_version(const string& v)
/// Getter of the regular expression for a family of versions of
/// symbol for the variables the user wants the current specification
-/// to designate. If @p symbol_version is not empty, then this
+/// to designate.
+///
+/// If the symbol version as returned by
+/// variable_suppression::get_symbol_version() is not empty, then this
/// property is ignored at evaluation time. This property might be
/// empty, in which case it's ignored at evaluation time.
///
@@ -3510,7 +3528,10 @@ variable_suppression::get_symbol_version_regex_str() const
/// Setter of the regular expression for a family of versions of
/// symbol for the variables the user wants the current specification
-/// to designate. If @p symbol_version is not empty, then this
+/// to designate.
+///
+/// If the symbol version as returned by
+/// variable_suppression::get_symbol_version() is not empty, then this
/// property is ignored at evaluation time. This property might be
/// empty, in which case it's ignored at evaluation time.
///