From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id AC0FBA0524; Wed, 5 May 2021 14:03:07 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 23B0540040; Wed, 5 May 2021 14:03:07 +0200 (CEST) Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by mails.dpdk.org (Postfix) with ESMTP id B1C6E4003C for ; Wed, 5 May 2021 14:03:05 +0200 (CEST) IronPort-SDR: FbXdOZZuyTHccmgsuPy/+aSqrcrwI3J7jUrmRrxMY2uOgO5etLprB9fnSS62fuTAdneeyXHoem ewiBSWDSvqIw== X-IronPort-AV: E=McAfee;i="6200,9189,9974"; a="198247085" X-IronPort-AV: E=Sophos;i="5.82,274,1613462400"; d="scan'208";a="198247085" Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 05 May 2021 05:03:04 -0700 IronPort-SDR: iipKsMEZopGYbiFEpRuK3GdmUcHHY+jQUyJCwJkoczX4Sgti7TeMzsdi32TcqqYGA5/6OD7TJW Rp0tH+gU7e7Q== X-IronPort-AV: E=Sophos;i="5.82,274,1613462400"; d="scan'208";a="468929502" Received: from aburakov-mobl.ger.corp.intel.com (HELO [10.213.210.178]) ([10.213.210.178]) by orsmga001-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 05 May 2021 05:03:02 -0700 To: Thomas Monjalon , Conor Walsh , Ferruh Yigit Cc: john.mcnamara@intel.com, david.marchand@redhat.com, bruce.richardson@intel.com, dev@dpdk.org References: <20210421091146.1384708-1-conor.walsh@intel.com> <3962445.YuhGqRbsoE@thomas> <27d6ea7a-d7c7-431b-d4a5-f1bc852e3a1f@intel.com> <3104956.X4MqZOROy4@thomas> From: "Burakov, Anatoly" Message-ID: Date: Wed, 5 May 2021 13:02:59 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.10.0 MIME-Version: 1.0 In-Reply-To: <3104956.X4MqZOROy4@thomas> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit Subject: Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On 04-May-21 12:56 PM, Thomas Monjalon wrote: > 04/05/2021 13:15, Ferruh Yigit: >> On 5/4/2021 11:44 AM, Thomas Monjalon wrote: >>> 04/05/2021 12:35, Ferruh Yigit: >>>> On 5/4/2021 10:59 AM, Thomas Monjalon wrote: >>>>> 04/05/2021 11:32, Burakov, Anatoly: >>>>>> On 03-May-21 10:02 PM, Thomas Monjalon wrote: >>>>>>> 21/04/2021 11:11, Conor Walsh: >>>>>>>> + The following will include a snippet from the skeleton sample app:: >>>>>>>> + >>>>>>>> + .. literalinclude:: ../../../examples/skeleton/basicfwd.c >>>>>>>> + :language: c >>>>>>>> + :start-after: Display the port MAC address. >>>>>>>> + :end-before: Enable RX in promiscuous mode for the Ethernet device. >>>>>>>> + :dedent: 1 >>>>>>> >>>>>>> I would prefer indenting the options with 3 spaces >>>>>>> to make them aligned with literalinclude. >>>>>>> >>>>>>> [...] >>>>>>>> +* ``start-after`` and ``end-before`` can use any text within a given file, >>>>>>>> + however it may be difficult to find unique text within your code to mark the >>>>>>>> + start and end of your snippets. In these cases, it is recommended to include >>>>>>>> + explicit tags in your code to denote these locations for documentation purposes. >>>>>>>> + >>>>>>>> + This can be done as follows: >>>>>>>> + >>>>>>>> + .. code-block:: c >>>>>>>> + >>>>>>>> + /* #guide_doc: Example feature being documented. */ >>>>>>>> + ... >>>>>>>> + /* #guide_doc: End of example feature being documented. */ >>>>>>> >>>>>>> I think we can standardize this usage in a beautiful syntax. >>>>>>> My proposal, using the scissor sign: >>>>>>> >>>>>>> /* Foo bar >8 */ >>>>>>> foo(bar); >>>>>>> /* 8< End of foo bar */ >>>>>>> >>>>>>> .. literalinclude:: foobar.c >>>>>>> :language: C >>>>>>> :start-after: Foo bar >8 >>>>>>> :end-before: 8< End of foo bar >>>>>>> >>>>>>> Another idea: >>>>>>> >>>>>>> /*~ Foo bar */ >>>>>>> foo(bar); >>>>>>> /*~ End of foo bar */ >>>>>>> >>>>>>> .. literalinclude:: foobar.c >>>>>>> :language: C >>>>>>> :start-after: ~ Foo bar >>>>>>> :end-before: ~ End of foo bar >>>>>>> >>>>>>> Maybe we don't need any markup for the start line and keep it natural: >>>>>>> >>>>>>> /* Foo bar */ >>>>>>> foo(bar); >>>>>>> /* end: Foo bar */ >>>>>>> >>>>>>> .. literalinclude:: foobar.c >>>>>>> :language: C >>>>>>> :start-after: Foo bar >>>>>>> :end-before: end: Foo bar >>>>>> >>>>>> Not having markup will 1) risk people accidentally "fixing" or otherwise >>>>>> modifying comments, and 2) has bigger potential for collisions elsewhere >>>>>> in the comments. While these aren't big risks, IMO it should be >>>>>> explicitly obvious that a comment is not just a comment but a marker docs. >>>>>> >>>>>> Having named tags like in the original proposal is the most explicit >>>>>> version of the above, which is why i favor it, but i think it's OK to >>>>>> have a lighter-weight syntax (e.g. with scissors for example), however i >>>>>> don't think it's a good idea to leave things implicit like your last >>>>>> suggestion. >>>>> >>>>> I think the first comment is not only for code extraction, >>>>> but also for code reader, that's why I think it's good to keep it natural. >>>> >>>> +1 to Anatoly's comment, to make it obvious to the reader of the code that the >>>> comment is used for documentation purposes and use explicit syntax for it. >>> >>> So you assume the comment is only for doc extraction? >>> I think it can be a real comment, otherwise we'll need to have >>> 2 lines: 1 for doc extraction, 1 for code comment. >>> >> >> I see your point, for the cases that there is already a comment before (or >> after) the code, will it be too bad to have multiple lines, something like: >> >> /* Actual comment >> * More details >> * >> * explicit marker */ >> >> >> I think explicit marker has the advantage of: >> - Whoever updating the comment will know that it is a marker for the >> documentation and be careful on update >> - Whoever updating the code between the markers, know that it may be required to >> re-visit the relevant documentation and update it because of code change >> - Whoever reading the code will know that part is in a documentation, and may be >> interested to go and check the relevant documentation >> - Whoever reading the code, and not very familiar with DPDK convention, still >> can understand what that comment is for and benefit from above > > I understand these points. > But I'm afraid the proposed syntax #guide_doc: > is not so obvious for everybody. > > I'm sure there can be a better syntax. > I'm not particularly attached to either syntax, as long as it's clearly documented and explicitly visible in the code (as opposed to something that kinda-sorta-but-doesn't-really-look-like-a-marker type syntax). So, we'd have to give up some "natural-ness", as *that's the point* of having a syntax. And i'm certainly OK with comment style like this: /* * some meaningful comment. * :doc_marker: */ ... /* :end doc_marker: */ Or something to that effect. What i'm *not* in favor of is these markers looking like part of a comment, rather than markers for doxygen. -- Thanks, Anatoly