From patchwork Mon Aug 17 09:38:19 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Giuliano Procida X-Patchwork-Id: 40278 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id F1D42385E445; Mon, 17 Aug 2020 09:38:46 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org F1D42385E445 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1597657127; bh=3HKZ0likPxFi9MQnMHdqtRFdNpZIn57KOXAGV4rbi2I=; h=Date:In-Reply-To:References:Subject:To:List-Id:List-Unsubscribe: List-Archive:List-Help:List-Subscribe:From:Reply-To:Cc:From; b=wqnGv/yF8sxZxTi/diNVU6GeEuAXzBHbrDyF/6SZ1aXiuCjePPH2iCIjKgWBQAFEf 6l+pwJMokESqmbRxNv//RkNnFA2dCRKoyxzJ9gTaf1TkR8M/lifoTPFByM2MSo4lRN W0WhfLFOewUhAp+8PydAbydyydnBbbCvQGItWmZY= X-Original-To: libabigail@sourceware.org Delivered-To: libabigail@sourceware.org Received: from mail-ej1-x649.google.com (mail-ej1-x649.google.com [IPv6:2a00:1450:4864:20::649]) by sourceware.org (Postfix) with ESMTPS id EA54F385700C for ; Mon, 17 Aug 2020 09:38:43 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org EA54F385700C Received: by mail-ej1-x649.google.com with SMTP id r14so5299089eji.16 for ; Mon, 17 Aug 2020 02:38:43 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:in-reply-to:message-id:mime-version :references:subject:from:to:cc; bh=3HKZ0likPxFi9MQnMHdqtRFdNpZIn57KOXAGV4rbi2I=; b=GfKP0FFnu0nl3oji32Llwq/9SZkLRbq+Cq5oL0lJnrXuXOyvcUGew7q66h1attn7Dh CP/8qSyO7MlasL75PNBtx3ZEI+H6nyKyTmIV3VuuI7flebpIgVbpudQMaUUky0HRlTTv H5Kanlx251tEs1gwNHEhTh3OSui/Y76nS0WEDRBVJnrskUWlIwAWbyBxTPZQdLZM37Ki fwLwTS3d4KNoiER8m0J+6bTo0+8xyfq8Hr8wOmXcmayDG8lbBQU0tjT9DF0J2MsioO/n e0PL6xvh8v9XVe7k3UDN3wng1KxHJp6XJWWpeZNwGi0J8QBXVUn/k78vPRSwzUjK2LK7 qj8w== X-Gm-Message-State: AOAM533QVrsdEv7lVQkTcNhSBe3/QGI/2wfNgLL4D3tjPa6U30aakUwk tpyIO6hK9eDhjUTc1nkQ6ZYH6C/voFm4rWLILhu6EHeAdfaow+dEiHbghQUIHe36+xJULq0OlCT pAGsanodHpVdIU7H+ohCcOL7GPO/xjMa7vbS7FsTr7lEPPwpvKlgPZphQ/VOuZ4gzY+NldZc= X-Google-Smtp-Source: ABdhPJwrCz4yUe+7IBPibT2ZaLxE6BtFdx5xSIRT4l/oDMkG0OUiApWzRZ6VgxgR/sptOb4iPGsjUf0R6MY70w== X-Received: by 2002:a50:fa99:: with SMTP id w25mr14478941edr.150.1597657122762; Mon, 17 Aug 2020 02:38:42 -0700 (PDT) Date: Mon, 17 Aug 2020 10:38:19 +0100 In-Reply-To: <20200817093819.172380-1-gprocida@google.com> Message-Id: <20200817093819.172380-8-gprocida@google.com> Mime-Version: 1.0 References: <20200817093819.172380-1-gprocida@google.com> X-Mailer: git-send-email 2.28.0.220.ged08abb693-goog Subject: [PATCH 7/7] Refresh getter/setter comments. To: libabigail@sourceware.org X-Spam-Status: No, score=-21.6 required=5.0 tests=BAYES_00, DKIMWL_WL_MED, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP, USER_IN_DEF_DKIM_WL autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libabigail@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Mailing list of the Libabigail project List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-Patchwork-Original-From: Giuliano Procida via Libabigail From: Giuliano Procida Reply-To: Giuliano Procida Cc: kernel-team@android.com Errors-To: libabigail-bounces@sourceware.org Sender: "Libabigail" 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 --- 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. ///