Received-SPF: pass (google.com: domain of linux-kernel+bounces-9130-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Date: Thu, 21 Dec 2023 14:28:22 -0800
From: Ira Weiny <ira.weiny@intel.com>
To: Randy Dunlap <rdunlap@infradead.org>, <linux-kernel@vger.kernel.org>
CC: Randy Dunlap <rdunlap@infradead.org>, Dan Williams
	<dan.j.williams@intel.com>, Vishal Verma <vishal.l.verma@intel.com>, "Dave
 Jiang" <dave.jiang@intel.com>, Ira Weiny <ira.weiny@intel.com>,
	<nvdimm@lists.linux.dev>
Subject: Re: [PATCH 2/3] nvdimm/dimm_devs: fix kernel-doc for function params
Message-ID: <6584bc064ea54_5580229435@iweiny-mobl.notmuch>
References: <20231207210545.24056-1-rdunlap@infradead.org>
 <20231207210545.24056-2-rdunlap@infradead.org>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <20231207210545.24056-2-rdunlap@infradead.org>
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?iBO8riNswaXBqq2F29IR5MSJvla8lPoqP14CpL5wZZxiGtl0qiVmUI4prUYk?=
 =?us-ascii?Q?UruYKr3dg/wWogcgX+buFkSSsKoerAwTIHbM/MokzdQdEOwWI2b6Gq7M2/Ly?=
 =?us-ascii?Q?SVVQpihZZ89z4gUB5gipDglDyalFzPvXoNIs/zaQdFC0iJTQlwq8jtewN7g4?=
 =?us-ascii?Q?o4y/5vGajgaTkDDNSXaqHzPkoYEYnq5JiNHs/2a4wML/nQp7VXSbuIjN9qQw?=
 =?us-ascii?Q?WdGUVTya4UU/G0gJwAU2FR2s7O7QHSihFzWUBoBSUh7ITDilO+Sf1UgaQzCT?=
 =?us-ascii?Q?5bq6ZzbgL7BtIyOnnjKDFUzH2VdXxfgGcICkU+CLh/Taf+vF4Hom7Q4tfi1C?=
 =?us-ascii?Q?L0b0XFg8/hND//IKW9tbxvD7IE6ToWcvZ3DUMTrBYz09OvdMe0fSFL1ZtYw3?=
 =?us-ascii?Q?XqwH3tlGtGUukumwCigy8nWU5UX8tPtDf4WXKfXz7AgqAe0PrlI3A7VtD/zm?=
 =?us-ascii?Q?HYGXpfya5mJPucurpVY2BaqVbffLq/6oSq67ryrUdJS9gAHz6/xzSrq/LR/C?=
 =?us-ascii?Q?V/dmiz/N569sVHJxwhK5EX+HBNorBfSVhgLGmb6RhB4cH1RDVLjh7HtL10+R?=
 =?us-ascii?Q?JlkmzzOaEWzXWXq+oBGQ6ZtcUwAbBbzrD1MhXT/y7RupBJyc8GZbnSemTMUm?=
 =?us-ascii?Q?1hCbj8s56ozpdX8EUljYqI4Syo7wOuJESMNigEEF56SXCXpuW8+ZD3WxWw44?=
 =?us-ascii?Q?1e3liFyXC6H45M9WW/3zZXPKDZfkd1EjIE/xGT3Ozs73RUcwE+pegq8PHL8W?=
 =?us-ascii?Q?NjsNRiupiKVC3S0840p4Bv2jwJn4hPnVm9ajHmMUo5L8TlQronEGzNvlQIPH?=
 =?us-ascii?Q?FaHOecYkPScUK1hFQMAFEeSVQpCv1qlHhy2qpi5ceP6Zo6Cp8TSuqU6me8tT?=
 =?us-ascii?Q?k3dx+2A6gXW5N/jX+g2FQ9IQ50DVFoZhSm3IiTGUXEbJ5l/MFiFUh6IMQv39?=
 =?us-ascii?Q?FXWR9qkI0xvOZ58Aw37nWz0z/4XUlcECfQYb/5DouABWu6Re++Snurjh0PNf?=
 =?us-ascii?Q?l+b0HFRCSs8WiAnEHtxKojwtXcTZl9NaIB8+6CpSgr5+x7Gql4jmArKUO3N8?=
 =?us-ascii?Q?WYiNsLQlU47joh7H00K5WT5UjweqR0nhfsJ5Fl94xBEvNaXYxO3mTE6n+7Z9?=
 =?us-ascii?Q?Bc5UlrCa4H8MbKKIGet04se4QQ7JpEZjAJ8GdHr0uTBqnJ7CbFPfNs921ts7?=
 =?us-ascii?Q?wSuKecXcwM5rLoc4mlgPOawu+Yyk6sQJvqgQE9XSSuGA5jMKuOK9jqVaYeQA?=
 =?us-ascii?Q?e8ENM+BBVew/1A8OXUQgLCTNEU0QSBgeO0UElMo3heNTc6Y/VOEyINjBFbFr?=
 =?us-ascii?Q?FmeqcjVl7h1dqV+pjYJTaF3E/sd7EgQX9mCe+SG/3WH5O9RHc5TgSPgifYed?=
 =?us-ascii?Q?dkNcTYe12sYEs6SiI31Wujeb753+8cMyYJFtqBt8FBJMuX9TniAl2Koz4I4p?=
 =?us-ascii?Q?BNCWcS/g/7QzcJvIujkLcn/ZT4SbiSlWd2GyowGXqRZ2Md1caO0BqVhlKX7h?=
 =?us-ascii?Q?aH8Nx3OX0njZKFwTVOU06kTe0gCnl7JB4DRiZktCctGszlGqORDWUMLV92+t?=
 =?us-ascii?Q?nZ1+uizvYA4n+UWNwKzEk/8cQ/gJ6crjhM3blNLJ?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 9e37d622-9d19-4505-b7b5-08dc02742633
X-MS-Exchange-CrossTenant-AuthSource: SA1PR11MB6733.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 21 Dec 2023 22:28:26.2084
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: Og8KtuwuThvLqn5SQGIA43lvlpayOTGC/mEpqnAGZ4nQpKoaOe+TR/SREuWkIueVoB1Zi7xGV7hrp1NZSiDmjw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: LV8PR11MB8488
X-OriginatorOrg: intel.com

Randy Dunlap wrote:
> Adjust kernel-doc notation to prevent warnings when using -Wall.
> 
> dimm_devs.c:59: warning: Function parameter or member 'ndd' not described in 'nvdimm_init_nsarea'
> dimm_devs.c:59: warning: Excess function parameter 'nvdimm' description in 'nvdimm_init_nsarea'
> dimm_devs.c:59: warning: No description found for return value of 'nvdimm_init_nsarea'
> dimm_devs.c:728: warning: No description found for return value of 'nd_pmem_max_contiguous_dpa'
> dimm_devs.c:773: warning: No description found for return value of 'nd_pmem_available_dpa'
> dimm_devs.c:844: warning: Function parameter or member 'ndd' not described in 'nvdimm_allocated_dpa'
> dimm_devs.c:844: warning: Excess function parameter 'nvdimm' description in 'nvdimm_allocated_dpa'
> dimm_devs.c:844: warning: No description found for return value of 'nvdimm_allocated_dpa'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Dan Williams <dan.j.williams@intel.com>
> Cc: Vishal Verma <vishal.l.verma@intel.com>
> Cc: Dave Jiang <dave.jiang@intel.com>
> Cc: Ira Weiny <ira.weiny@intel.com>
> Cc: nvdimm@lists.linux.dev
> ---
>  drivers/nvdimm/dimm_devs.c |   14 ++++++++++++--
>  1 file changed, 12 insertions(+), 2 deletions(-)
> 
> diff -- a/drivers/nvdimm/dimm_devs.c b/drivers/nvdimm/dimm_devs.c
> --- a/drivers/nvdimm/dimm_devs.c
> +++ b/drivers/nvdimm/dimm_devs.c
> @@ -53,7 +53,10 @@ static int validate_dimm(struct nvdimm_d
>  
>  /**
>   * nvdimm_init_nsarea - determine the geometry of a dimm's namespace area
> - * @nvdimm: dimm to initialize
> + * @ndd: dimm to initialize
> + *
> + * Returns: %0 if the area is already valid, -errno on error,

This is good...

> ...otherwise an
> + * ND_CMD_* status code.

I don't see where any of the ->ndctl() calls return an ND_CMD_* status
code.  What am I missing?

The rest looks good,
Ira

>   */
>  int nvdimm_init_nsarea(struct nvdimm_drvdata *ndd)
>  {
> @@ -722,6 +725,9 @@ static unsigned long dpa_align(struct nd
>   *			   contiguous unallocated dpa range.
>   * @nd_region: constrain available space check to this reference region
>   * @nd_mapping: container of dpa-resource-root + labels
> + *
> + * Returns: %0 if there is an alignment error, otherwise the max
> + *		unallocated dpa range
>   */
>  resource_size_t nd_pmem_max_contiguous_dpa(struct nd_region *nd_region,
>  					   struct nd_mapping *nd_mapping)
> @@ -767,6 +773,8 @@ resource_size_t nd_pmem_max_contiguous_d
>   *
>   * Validate that a PMEM label, if present, aligns with the start of an
>   * interleave set.
> + *
> + * Returns: %0 if there is an alignment error, otherwise the unallocated dpa
>   */
>  resource_size_t nd_pmem_available_dpa(struct nd_region *nd_region,
>  				      struct nd_mapping *nd_mapping)
> @@ -836,8 +844,10 @@ struct resource *nvdimm_allocate_dpa(str
>  
>  /**
>   * nvdimm_allocated_dpa - sum up the dpa currently allocated to this label_id
> - * @nvdimm: container of dpa-resource-root + labels
> + * @ndd: container of dpa-resource-root + labels
>   * @label_id: dpa resource name of the form pmem-<human readable uuid>
> + *
> + * Returns: sum of the dpa allocated to the label_id
>   */
>  resource_size_t nvdimm_allocated_dpa(struct nvdimm_drvdata *ndd,
>  		struct nd_label_id *label_id)