From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8C0FB1E8855; Tue, 17 Dec 2024 15:03:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734447793; cv=none; b=ptvUxAhu5u/V8BoX6wRamSJjUAIGsZTVuYafe1lTw7nB2WAt14OjV131pHu79D6h+bTcPyQtmNPzPyzuNJ//sDSMpvamvQAMp+jP1YOD38SQisQ6qplrqQEQhufRMjQ6y3KToMpOA+hXMOM4tVNrzGAXBypDKQgkEQm5HJyJe6U= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734447793; c=relaxed/simple; bh=YjeHqn7JMtfcLWDTg6uquZsAt1ZAnNU7dpzXtPwL3Bk=; h=Date:From:To:Cc:Subject:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=CHuu4yQZrPmNLFZeg8TAGqWK70ZnwO2mKBE3oh3RAWNfTJ+N4j5CRJkFApHAIuJcEYnksuv93noCvcKyOsqs8Mteu3ZGy+SaatPFaaJdut7pfrJOxh23cuo0pl1Ys7Rcc4WB1o5eEr+GNCbiNQFOfhEohBooTqW8ylzIquh/N5w= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=LQ1A4wbT; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="LQ1A4wbT" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 68BEAC4CED3; Tue, 17 Dec 2024 15:03:12 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1734447793; bh=YjeHqn7JMtfcLWDTg6uquZsAt1ZAnNU7dpzXtPwL3Bk=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=LQ1A4wbT7Za8PMBkb2n0TW8RJgkLNHJyjeMBcxKz4/BAFYHasK/wq/dX13CXaA8Po ypnLkzDSAWvf22W6cDWBRuBhroWVmLtxBNYCnAkekcoL2XdezusefarDo/T9e+qzcZ im9bKLadYyve4wMneVjwb+vgeuwi0NkJUErvi1WHAqUsUB69PDozBlY7ZHOG4ojTBW V4DzN18bPriFEU8PYozLF6hOqZhojdf+x1dcCWiAmXJDsErIrovtvrbdvW8kRYPKhC /teFWbk/a3pQ0ryt7PsXOmzC/AY8Q0qzCVL17kCA2IZgzr7vb1D/IPhpXirhQgkEwv qm3kfiEE0+JNA== Date: Tue, 17 Dec 2024 07:03:11 -0800 From: Jakub Kicinski To: Oleksij Rempel Cc: "Russell King (Oracle)" , Paolo Abeni , "David S. Miller" , Eric Dumazet , Andrew Lunn , Heiner Kallweit , Jonathan Corbet , kernel@pengutronix.de, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Simon Horman , Maxime Chevallier , linux-doc@vger.kernel.org Subject: Re: [PATCH net-next v1 1/1] net: phy: Move callback comments from struct to kernel-doc section Message-ID: <20241217070311.1c867d32@kernel.org> In-Reply-To: References: <20241206113952.406311-1-o.rempel@pengutronix.de> <20241210063704.09c0ac8a@kernel.org> <20241216175316.6df45645@kernel.org> Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit On Tue, 17 Dec 2024 06:40:51 +0100 Oleksij Rempel wrote: > > > Please rephrase, I do not understand. > > > > > > Should I resend this patch with corrected "Return:" description, or > > > continue with inlined comments withing the struct and drop this patch? > > > > I'm not talking about Returns, I'm talking about the core idea of > > the patch. The duplicate definitions seem odd, can we teach kernel-doc > > to understand function args instead? Most obvious format which comes > > to mind: > > > > * ... > > * @config_init - Initialize the PHY, including after a reset. > > * @config_init.phydev: The PHY device to initialize. > > * > > * Returns: 0 on success or a negative error code on failure. > > * ... > > It will be too many side quests to me for now. I can streamline comments > if there is agreement how it should look like. But fixing kdoc - I would leave > it to the experts. > > What do you prefer, proceed with stats patch without fixing comments or > fix comment without fixing kdoc? The former. And you're using the word "fix" very loosely here, IMHO.