From: Giuliano Procida <gprocida@google.com>
To: libabigail@sourceware.org
Cc: dodji@seketeli.org, kernel-team@android.com, gprocida@google.com
Subject: [PATCH 7/7] Refresh getter/setter comments.
Date: Mon, 17 Aug 2020 10:38:19 +0100 [thread overview]
Message-ID: <20200817093819.172380-8-gprocida@google.com> (raw)
In-Reply-To: <20200817093819.172380-1-gprocida@google.com>
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(-)
diff --git a/src/abg-suppression.cc b/src/abg-suppression.cc
index c9b2390e0..a1935385d 100644
--- a/src/abg-suppression.cc
+++ b/src/abg-suppression.cc
@@ -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.
///
--
2.28.0.220.ged08abb693-goog
next prev parent reply other threads:[~2020-08-17 9:38 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-08-17 9:38 [PATCH 0/7] Suppression parsing - preparatory work Giuliano Procida
2020-08-17 9:38 ` [PATCH 1/7] Add missing newlines to end of test files Giuliano Procida
2020-10-01 14:36 ` Dodji Seketeli
2020-08-17 9:38 ` [PATCH 2/7] Fix two wrongs in test suppression regex Giuliano Procida
2020-10-01 14:42 ` Dodji Seketeli
2020-08-17 9:38 ` [PATCH 3/7] Better suppression section parsing delegation Giuliano Procida
2020-10-01 15:56 ` Dodji Seketeli
2020-10-02 7:20 ` Giuliano Procida
2020-08-17 9:38 ` [PATCH 4/7] Add read_*_suppression success/failure plumbing Giuliano Procida
2020-08-17 9:38 ` [PATCH 5/7] Add error handling to read_suppressions Giuliano Procida
2020-08-17 9:38 ` [PATCH 6/7] Default construct suppression types Giuliano Procida
2020-08-17 9:38 ` Giuliano Procida [this message]
2020-10-02 7:25 ` [PATCH 0/7] Suppression parsing - preparatory work Dodji Seketeli
2020-10-06 20:19 ` Giuliano Procida
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200817093819.172380-8-gprocida@google.com \
--to=gprocida@google.com \
--cc=dodji@seketeli.org \
--cc=kernel-team@android.com \
--cc=libabigail@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).