From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
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 <dev@dpdk.org>; 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 <thomas@monjalon.net>, Conor Walsh
 <conor.walsh@intel.com>, Ferruh Yigit <ferruh.yigit@intel.com>
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" <anatoly.burakov@intel.com>
Message-ID: <d679d898-0768-7a4e-20de-c60044223c95@intel.com>
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 <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

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