From patchwork Tue Aug 27 09:55:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Chen-Yu Tsai X-Patchwork-Id: 13779219 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 9058AC52D6F for ; Tue, 27 Aug 2024 10:00:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender:List-Subscribe:List-Help :List-Post:List-Archive:List-Unsubscribe:List-Id:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=7LLSsNj3le8TWETIDzCV0x45IW45F1GT/zaPgv3xeew=; b=XP9yiXo0IkFFeFkll3fsuVg49D g/MqKWe/FErJaHr5I36QwN4EnTcA5bf2W4Zzgw2VereRGjbp+hfW5ENdwIMjd/r+l9XHZTr7VNZnn LQgagQHsshtMtBDv+uUqphdGNC4c/rqk7bvQHaN02ipkO4TQu+rv1hyWB5Jec5p5bP+H+csjMbXGN 2HVizyR5ZkfPWFeLBkWhPp8FjzR+zTndtRiKiHSma+oil9XB8cXizxQwIyxts5ymyXnSixNyeqk8p eSN6Y6D+RseATEtYyac/rzwiZKNz5g4Ugn/FUxNMY+Lp40QDf69XEBqqaRPgu9Z9O+bJP3DWmvmOQ qeWHL+7A==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.97.1 #2 (Red Hat Linux)) id 1siszg-0000000Ahh1-0cfV; Tue, 27 Aug 2024 10:00:08 +0000 Received: from mail-pl1-x62f.google.com ([2607:f8b0:4864:20::62f]) by bombadil.infradead.org with esmtps (Exim 4.97.1 #2 (Red Hat Linux)) id 1sisvk-0000000AgYf-2NCm for linux-arm-kernel@lists.infradead.org; Tue, 27 Aug 2024 09:56:06 +0000 Received: by mail-pl1-x62f.google.com with SMTP id d9443c01a7336-201fbd0d7c2so43046225ad.0 for ; Tue, 27 Aug 2024 02:56:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; t=1724752563; x=1725357363; darn=lists.infradead.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=7LLSsNj3le8TWETIDzCV0x45IW45F1GT/zaPgv3xeew=; b=DHj+n9RSVOTXDhWHTRYgUtnoCSw4dOALczORV/FDC/6jm+pQTRSXQSy8hdHMYrIlQb UZ7rtoa78k6MxjQE/DN0fULmFiUkckHM1OUltuX8ZYNfNQZb5eKYdXMIYEBs6LUL2eTe cT0Ci2n9/dK/BfdyDZMZH0gCG0BopGdtL+XCc= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1724752563; x=1725357363; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=7LLSsNj3le8TWETIDzCV0x45IW45F1GT/zaPgv3xeew=; b=BMagvfaqCCDIAH6EDOdfkYn9uLBYsQop76wNcMBxUENE363T4HlD/3GrTy+bNRcDs1 81WeDSPBuVuJ4L3CMY1z9hfM5K5qqLnoPTE1nzqYYs2nDiH8fGk9rxibNoGkVY+aRlmr 4NPYQKcvSnp2IF6Uhw92fg3bJ6THOm1/Mm9yrub3RYOmD/89lxCCIVLPROLKZnde+7qN bZZ9VKacrX2fGdmMpIb9+ZBKy4LEWNEVVqRRn3wrFqVpdnOSWlOHrJtvwPd+BO5qKfqU Ji1OUd1d9CaKLit/p/dc2X/XndNXdNjeXNs7bCXevULqSI9VVywJVljpRt2b7LwZuoZQ h4vw== X-Forwarded-Encrypted: i=1; AJvYcCV4YzQY5Ps6Uizqs7JxBnqdNFz3y+16VYy7zK8yNWMGA+Mhk3Yes7aZ77tetl4Ah59cvcjx+BpZ+tM4iik4m1bT@lists.infradead.org X-Gm-Message-State: AOJu0Yz/mzsLLUvfwpFtG42bozyfh9PpYGTKPJK8kUcJpP2opg6RrI8H lH3nXEmNZKoVuBcnmerozaEbL2gqg6nTHnqPCuc6vyRoVfDKZoTpQA8VrMhR1g== X-Google-Smtp-Source: AGHT+IHnP0UxGHShDudSxRf4EKVdCozcxdusgqEAENCL/YU2wzK66FdkoWkYdwQomaRjL9BY0Eb7tw== X-Received: by 2002:a17:902:c411:b0:203:a046:c676 with SMTP id d9443c01a7336-204ddfe8059mr21403475ad.0.1724752563346; Tue, 27 Aug 2024 02:56:03 -0700 (PDT) Received: from wenstp920.tpe.corp.google.com ([2401:fa00:1:10:3102:657e:87f4:c646]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-2038560c2basm80006775ad.222.2024.08.27.02.56.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 27 Aug 2024 02:56:03 -0700 (PDT) From: Chen-Yu Tsai To: Mark Brown , Liam Girdwood Cc: Chen-Yu Tsai , linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, Andy Shevchenko Subject: [PATCH 3/8] regulator: core: Fix incorrectly formatted kerneldoc "Return" sections Date: Tue, 27 Aug 2024 17:55:43 +0800 Message-ID: <20240827095550.675018-4-wenst@chromium.org> X-Mailer: git-send-email 2.46.0.295.g3b9ea8a38a-goog In-Reply-To: <20240827095550.675018-1-wenst@chromium.org> References: <20240827095550.675018-1-wenst@chromium.org> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20240827_025604_639243_C36425B4 X-CRM114-Status: GOOD ( 31.10 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org kernel-doc complains about missing "Return" section for many documented functions in the regulator core. Many of them actually have descriptions about the return values, just not in the format kernel-doc wants. Convert these to use the proper "Return:" section header. The existing descriptions have been reworded and moved around to fit the grammar and formatting. In a few cases where the functions don't call even more functions and the error numbers are known, those are documented in detail. Signed-off-by: Chen-Yu Tsai --- drivers/regulator/core.c | 101 ++++++++++++++++++++++----------------- 1 file changed, 56 insertions(+), 45 deletions(-) diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c index 3a1b6fd9780d..b1950cbc046a 100644 --- a/drivers/regulator/core.c +++ b/drivers/regulator/core.c @@ -427,8 +427,9 @@ static void regulator_lock_dependent(struct regulator_dev *rdev, * * Traverse all child nodes. * Extract the child regulator device node corresponding to the supply name. - * returns the device node corresponding to the regulator if found, else - * returns NULL. + * + * Return: pointer the &struct device_node corresponding to the regulator if found, + * or %NULL if not found. */ static struct device_node *of_get_child_regulator(struct device_node *parent, const char *prop_name) @@ -460,8 +461,9 @@ static struct device_node *of_get_child_regulator(struct device_node *parent, * @supply: regulator supply name * * Extract the regulator device node corresponding to the supply name. - * returns the device node corresponding to the regulator if found, else - * returns NULL. + * + * Return: pointer the &struct device_node corresponding to the regulator if found, + * or %NULL if not found. */ static struct device_node *of_get_regulator(struct device *dev, const char *supply) { @@ -2308,13 +2310,13 @@ struct regulator *_regulator_get(struct device *dev, const char *id, * @dev: device for regulator "consumer" * @id: Supply name or regulator ID. * - * Returns a struct regulator corresponding to the regulator producer, - * or IS_ERR() condition containing errno. - * * Use of supply names configured via set_consumer_device_supply() is * strongly encouraged. It is recommended that the supply name used * should match the name used for the supply and/or the relevant * device pins in the datasheet. + * + * Return: pointer to a &struct regulator corresponding to the regulator + * producer, or ERR_PTR() encoded negative error number. */ struct regulator *regulator_get(struct device *dev, const char *id) { @@ -2327,11 +2329,9 @@ EXPORT_SYMBOL_GPL(regulator_get); * @dev: device for regulator "consumer" * @id: Supply name or regulator ID. * - * Returns a struct regulator corresponding to the regulator producer, - * or IS_ERR() condition containing errno. Other consumers will be - * unable to obtain this regulator while this reference is held and the - * use count for the regulator will be initialised to reflect the current - * state of the regulator. + * Other consumers will be unable to obtain this regulator while this + * reference is held and the use count for the regulator will be + * initialised to reflect the current state of the regulator. * * This is intended for use by consumers which cannot tolerate shared * use of the regulator such as those which need to force the @@ -2342,6 +2342,9 @@ EXPORT_SYMBOL_GPL(regulator_get); * strongly encouraged. It is recommended that the supply name used * should match the name used for the supply and/or the relevant * device pins in the datasheet. + * + * Return: pointer to a &struct regulator corresponding to the regulator + * producer, or ERR_PTR() encoded negative error number. */ struct regulator *regulator_get_exclusive(struct device *dev, const char *id) { @@ -2354,9 +2357,6 @@ EXPORT_SYMBOL_GPL(regulator_get_exclusive); * @dev: device for regulator "consumer" * @id: Supply name or regulator ID. * - * Returns a struct regulator corresponding to the regulator producer, - * or IS_ERR() condition containing errno. - * * This is intended for use by consumers for devices which can have * some supplies unconnected in normal use, such as some MMC devices. * It can allow the regulator core to provide stub supplies for other @@ -2368,6 +2368,9 @@ EXPORT_SYMBOL_GPL(regulator_get_exclusive); * strongly encouraged. It is recommended that the supply name used * should match the name used for the supply and/or the relevant * device pins in the datasheet. + * + * Return: pointer to a &struct regulator corresponding to the regulator + * producer, or ERR_PTR() encoded negative error number. */ struct regulator *regulator_get_optional(struct device *dev, const char *id) { @@ -2507,12 +2510,12 @@ EXPORT_SYMBOL_GPL(regulator_unregister_supply_alias); * lookup the supply * @num_id: Number of aliases to register * - * @return 0 on success, an errno on failure. - * * This helper function allows drivers to register several supply * aliases in one operation. If any of the aliases cannot be * registered any aliases that were registered will be removed * before returning to the caller. + * + * Return: 0 on success or negative error number on failure. */ int regulator_bulk_register_supply_alias(struct device *dev, const char *const *id, @@ -2837,7 +2840,7 @@ static int _regulator_do_enable(struct regulator_dev *rdev) * responsible for keeping track of the refcount for a given regulator consumer * and applying / unapplying these things. * - * Returns 0 upon no error; -error upon error. + * Return: 0 on success or negative error number on failure. */ static int _regulator_handle_consumer_enable(struct regulator *regulator) { @@ -2863,7 +2866,7 @@ static int _regulator_handle_consumer_enable(struct regulator *regulator) * * The opposite of _regulator_handle_consumer_enable(). * - * Returns 0 upon no error; -error upon error. + * Return: 0 on success or negative error number on failure. */ static int _regulator_handle_consumer_disable(struct regulator *regulator) { @@ -3271,13 +3274,13 @@ static int _regulator_list_voltage(struct regulator_dev *rdev, * regulator_is_enabled - is the regulator output enabled * @regulator: regulator source * - * Returns positive if the regulator driver backing the source/client - * has requested that the device be enabled, zero if it hasn't, else a - * negative errno code. - * * Note that the device backing this regulator handle can have multiple * users, so it might be enabled even if regulator_enable() was never * called for this particular source. + * + * Return: positive if the regulator driver backing the source/client + * has requested that the device be enabled, zero if it hasn't, else a + * negative error number. */ int regulator_is_enabled(struct regulator *regulator) { @@ -3298,9 +3301,10 @@ EXPORT_SYMBOL_GPL(regulator_is_enabled); * regulator_count_voltages - count regulator_list_voltage() selectors * @regulator: regulator source * - * Returns number of selectors, or negative errno. Selectors are - * numbered starting at zero, and typically correspond to bitfields - * in hardware registers. + * Return: number of selectors for @regulator, or negative error number. + * + * Selectors are numbered starting at zero, and typically correspond to + * bitfields in hardware registers. */ int regulator_count_voltages(struct regulator *regulator) { @@ -3322,9 +3326,9 @@ EXPORT_SYMBOL_GPL(regulator_count_voltages); * @selector: identify voltage to list * Context: can sleep * - * Returns a voltage that can be passed to @regulator_set_voltage(), - * zero if this selector code can't be used on this system, or a - * negative errno. + * Return: voltage for @selector that can be passed to regulator_set_voltage(), + * 0 if @selector can't be used on this system, or a negative error + * number on failure. */ int regulator_list_voltage(struct regulator *regulator, unsigned selector) { @@ -3336,8 +3340,8 @@ EXPORT_SYMBOL_GPL(regulator_list_voltage); * regulator_get_regmap - get the regulator's register map * @regulator: regulator source * - * Returns the register map for the given regulator, or an ERR_PTR value - * if the regulator doesn't use regmap. + * Return: pointer to &struct regmap for @regulator, or ERR_PTR() + * encoded -%EOPNOTSUPP if @regulator doesn't use regmap. */ struct regmap *regulator_get_regmap(struct regulator *regulator) { @@ -3387,7 +3391,9 @@ EXPORT_SYMBOL_GPL(regulator_get_hardware_vsel_register); * directly written to the regulator registers. The address of the voltage * register can be determined by calling @regulator_get_hardware_vsel_register. * - * On error a negative errno is returned. + * Return: 0 on success, -%EINVAL if the selector is outside the supported + * range, or -%EOPNOTSUPP if the regulator does not support voltage + * selectors. */ int regulator_list_hardware_vsel(struct regulator *regulator, unsigned selector) @@ -3414,7 +3420,7 @@ EXPORT_SYMBOL_GPL(regulator_list_hardware_vsel); * Request that the regulator be enabled/disabled with the regulator output at * the predefined voltage or current value. * - * On success 0 is returned, otherwise a negative errno is returned. + * Return: 0 on success or negative error number on failure. */ int regulator_hardware_enable(struct regulator *regulator, bool enable) { @@ -3438,8 +3444,8 @@ EXPORT_SYMBOL_GPL(regulator_hardware_enable); * regulator_get_linear_step - return the voltage step size between VSEL values * @regulator: regulator source * - * Returns the voltage step size between VSEL values for linear - * regulators, or return 0 if the regulator isn't a linear regulator. + * Return: the voltage step size between VSEL values for linear regulators, + * or 0 if the regulator isn't a linear regulator. */ unsigned int regulator_get_linear_step(struct regulator *regulator) { @@ -4526,7 +4532,7 @@ EXPORT_SYMBOL_GPL(regulator_get_voltage_rdev); * regulator_get_voltage - get regulator output voltage * @regulator: regulator source * - * This returns the current regulator voltage in uV. + * Return: current regulator voltage in uV, or negative error number on failure. * * NOTE: If the regulator is disabled it will return the voltage value. This * function should not be used to determine regulator state. @@ -4610,7 +4616,8 @@ static int _regulator_get_current_limit(struct regulator_dev *rdev) * regulator_get_current_limit - get regulator output current * @regulator: regulator source * - * This returns the current supplied by the specified current sink in uA. + * Return: current supplied by the specified current sink in uA, + * or negative error number on failure. * * NOTE: If the regulator is disabled it will return the current value. This * function should not be used to determine regulator state. @@ -4778,7 +4785,7 @@ EXPORT_SYMBOL_GPL(regulator_get_error_flags); * If a regulator is an always-on regulator then an individual consumer's * load will still be removed if that consumer is fully disabled. * - * On error a negative errno is returned. + * Return: 0 on success or negative error number on failure. */ int regulator_set_load(struct regulator *regulator, int uA_load) { @@ -4963,12 +4970,12 @@ int _regulator_bulk_get(struct device *dev, int num_consumers, * @num_consumers: Number of consumers to register * @consumers: Configuration of consumers; clients are stored here. * - * @return 0 on success, an errno on failure. - * * This helper function allows drivers to get several regulator * consumers in one operation. If any of the regulators cannot be * acquired then any regulators that were allocated will be freed * before returning to the caller. + * + * Return: 0 on success or negative error number on failure. */ int regulator_bulk_get(struct device *dev, int num_consumers, struct regulator_bulk_data *consumers) @@ -4989,12 +4996,13 @@ static void regulator_bulk_enable_async(void *data, async_cookie_t cookie) * * @num_consumers: Number of consumers * @consumers: Consumer data; clients are stored here. - * @return 0 on success, an errno on failure * * This convenience API allows consumers to enable multiple regulator * clients in a single API call. If any consumers cannot be enabled * then any others that were enabled will be disabled again prior to * return. + * + * Return: 0 on success or negative error number on failure. */ int regulator_bulk_enable(int num_consumers, struct regulator_bulk_data *consumers) @@ -5038,12 +5046,13 @@ EXPORT_SYMBOL_GPL(regulator_bulk_enable); * * @num_consumers: Number of consumers * @consumers: Consumer data; clients are stored here. - * @return 0 on success, an errno on failure * * This convenience API allows consumers to disable multiple regulator * clients in a single API call. If any consumers cannot be disabled * then any others that were disabled will be enabled again prior to * return. + * + * Return: 0 on success or negative error number on failure. */ int regulator_bulk_disable(int num_consumers, struct regulator_bulk_data *consumers) @@ -5077,7 +5086,6 @@ EXPORT_SYMBOL_GPL(regulator_bulk_disable); * * @num_consumers: Number of consumers * @consumers: Consumer data; clients are stored here. - * @return 0 on success, an errno on failure * * This convenience API allows consumers to forcibly disable multiple regulator * clients in a single API call. @@ -5085,6 +5093,8 @@ EXPORT_SYMBOL_GPL(regulator_bulk_disable); * likely occur if the regulators are not disabled (e.g. over temp). * Although regulator_force_disable function call for some consumers can * return error numbers, the function is called for all consumers. + * + * Return: 0 on success or negative error number on failure. */ int regulator_bulk_force_disable(int num_consumers, struct regulator_bulk_data *consumers) @@ -5581,8 +5591,9 @@ static struct regulator_coupler generic_regulator_coupler = { * @cfg: runtime configuration for regulator * * Called by regulator drivers to register a regulator. - * Returns a valid pointer to struct regulator_dev on success - * or an ERR_PTR() on error. + * + * Return: pointer to valid &struct regulator_dev on success + * or ERR_PTR() encoded negative error number on failure. */ struct regulator_dev * regulator_register(struct device *dev,