From mboxrd@z Thu Jan 1 00:00:00 1970 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 861BEC4167B for ; Tue, 5 Dec 2023 20:11:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1345806AbjLEULU (ORCPT ); Tue, 5 Dec 2023 15:11:20 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:35966 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232224AbjLEULM (ORCPT ); Tue, 5 Dec 2023 15:11:12 -0500 Received: from vps0.lunn.ch (vps0.lunn.ch [156.67.10.101]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 58884183; Tue, 5 Dec 2023 12:11:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lunn.ch; s=20171124; h=In-Reply-To:Content-Disposition:Content-Type:MIME-Version: References:Message-ID:Subject:Cc:To:From:Date:From:Sender:Reply-To:Subject: Date:Message-ID:To:Cc:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Content-Disposition:In-Reply-To:References; bh=jJ9sUxistCYfXxn3AjS422gVO2JAhtrQB/n0qsuzpCI=; b=K2GrCTqPGZyOyLOd4c8Hy7pukH 2n1l946J8qDLN59IrvFOKa//pddhem8F/rnq0m1bdxy6du0518ZbcAAbucA6svtLRytGX82xdSBsG oQEyIxyG7c54gl1NOemmR7yL2PFEtvzWqV518z6YtG6koHC9QdVC26wGREVOo1Fzx3YE=; Received: from andrew by vps0.lunn.ch with local (Exim 4.94.2) (envelope-from ) id 1rAbky-0028ZN-Ig; Tue, 05 Dec 2023 21:11:00 +0100 Date: Tue, 5 Dec 2023 21:11:00 +0100 From: Andrew Lunn To: Jeff Johnson Cc: "Russell King (Oracle)" , Jakub Kicinski , Christian Marangi , Florian Fainelli , Broadcom internal kernel review list , Heiner Kallweit , "David S. Miller" , Eric Dumazet , Paolo Abeni , David Epping , Vladimir Oltean , Harini Katakam , netdev@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org Subject: Re: [net-next PATCH v3 3/3] net: phy: add support for PHY package MMD read/write Message-ID: References: <20231204181752.2be3fd68@kernel.org> <51aae9d0-5100-41af-ade0-ecebeccbc418@lunn.ch> <656f37a6.5d0a0220.96144.356f@mx.google.com> <20231205072912.2d79a1d5@kernel.org> <91dcd8c3-ae86-4350-838d-62ddb62fa2bb@quicinc.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <91dcd8c3-ae86-4350-838d-62ddb62fa2bb@quicinc.com> Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org > Having worked with closed-source systems, especially VxWorks, for many > years (where the header files contain all the documentation), it just > seems strange to embed the documentation in the .c files. The key words here might be closed-source. With such black boxes, you don't have access the sources. You cannot look at the source to understand how a function works. In the open source world, the comments partially function as an introduction to reading the code and understanding what it does. You are also encouraged to change the code if needed, which in the closed source world you cannot do. Given this discussion, i now think putting the documentation in the .c file makes more sense. For the generated documentation it does not matter, but for the reader of the code, having it in the .c files does seem to make sense. Andrew