From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from metis.whiteo.stw.pengutronix.de (metis.whiteo.stw.pengutronix.de [185.203.201.7]) (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 9CD1F204C3F for ; Mon, 16 Dec 2024 12:20:35 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=185.203.201.7 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734351637; cv=none; b=iAeZR/3V/rxgD0WK8eXMvSo5LVwRv3tMTfNApnhRB4vh1DMYljod1JOHfo9UUHGp72vl3qyQiU+LwxxxdvyyWj1J4VEbDDpEvTbhYrAc7RRNi1p6SR5CLYyio8RwjoLeP34/GD7UqfMsDyHF9J/xoVUu+Kni1/k2xXOHpHfUhSw= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734351637; c=relaxed/simple; bh=+1mE4Amh1vSqq4XSBGGaKD1SEheJUziTYiTujI51/T4=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=KH4u86V0nenJBg4iH3WHB+lk6h3CbNX2dkaFFraWFJm9zI7jFhmfIXgksVLbLhqAvRU6HW93h3eLjBF3OJBCz/pZEoxoTbA1Poq0TdrgV4bgroDPGmD8QQ6gWMbrV1Zmd++6Mqm2O1Qd8EiCIpcESfCdTXTTucqjHqpAwylZOUA= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=pengutronix.de; spf=pass smtp.mailfrom=pengutronix.de; arc=none smtp.client-ip=185.203.201.7 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=pengutronix.de Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pengutronix.de Received: from drehscheibe.grey.stw.pengutronix.de ([2a0a:edc0:0:c01:1d::a2]) by metis.whiteo.stw.pengutronix.de with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tNA5H-0003o0-03; Mon, 16 Dec 2024 13:20:23 +0100 Received: from pty.whiteo.stw.pengutronix.de ([2a0a:edc0:2:b01:1d::c5]) by drehscheibe.grey.stw.pengutronix.de with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1tNA5F-003h3M-1D; Mon, 16 Dec 2024 13:20:22 +0100 Received: from ore by pty.whiteo.stw.pengutronix.de with local (Exim 4.96) (envelope-from ) id 1tNA5G-002ars-07; Mon, 16 Dec 2024 13:20:22 +0100 Date: Mon, 16 Dec 2024 13:20:22 +0100 From: Oleksij Rempel To: Jakub Kicinski 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: References: <20241206113952.406311-1-o.rempel@pengutronix.de> <20241210063704.09c0ac8a@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=utf-8 Content-Disposition: inline In-Reply-To: <20241210063704.09c0ac8a@kernel.org> X-Sent-From: Pengutronix Hildesheim X-URL: http://www.pengutronix.de/ X-Accept-Language: de,en X-Accept-Content-Type: text/plain X-SA-Exim-Connect-IP: 2a0a:edc0:0:c01:1d::a2 X-SA-Exim-Mail-From: ore@pengutronix.de X-SA-Exim-Scanned: No (on metis.whiteo.stw.pengutronix.de); SAEximRunCond expanded to false X-PTX-Original-Recipient: netdev@vger.kernel.org Hi Jakub, On Tue, Dec 10, 2024 at 06:37:04AM -0800, Jakub Kicinski wrote: > > I certainly can't help but write the "returns" statement in natural > > English, rather than kernel-doc "Returns:" style as can be seen from > > my recent patches that have been merged. "Returns" without a colon is > > just way more natural when writing documentation. > > > > IMHO, kernel-doc has made a wrong decision by requiring the colon. > > For the patch under consideration, however, I think _some_ attempt > to make fully documenting callbacks inline possible needs to be made :( 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? Regards, Oleksij -- Pengutronix e.K. | | Steuerwalder Str. 21 | http://www.pengutronix.de/ | 31137 Hildesheim, Germany | Phone: +49-5121-206917-0 | Amtsgericht Hildesheim, HRA 2686 | Fax: +49-5121-206917-5555 |