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 455D8A0562; Tue, 4 May 2021 11:32:35 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id C0FA640141; Tue, 4 May 2021 11:32:34 +0200 (CEST) Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by mails.dpdk.org (Postfix) with ESMTP id 6ADF84003E for ; Tue, 4 May 2021 11:32:33 +0200 (CEST) IronPort-SDR: ah5lt89Z5rJ2C6kMHzKgyWoF4lqONSCal0RBVNRG8PDEML0eUIqk9SOhcWXgFE8Fq9Uwd+D22a 2mfr4UfBn93Q== X-IronPort-AV: E=McAfee;i="6200,9189,9973"; a="177479632" X-IronPort-AV: E=Sophos;i="5.82,272,1613462400"; d="scan'208";a="177479632" Received: from orsmga001.jf.intel.com ([10.7.209.18]) by fmsmga106.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 04 May 2021 02:32:32 -0700 IronPort-SDR: /RtNVpNfCvd1PoDyAYxwduQ/rrefmcC5j4rK1zHvx3kz05zqRTH4Ow7YZo6HfS3sCsOHuW3BHI MXwvDn65sWgQ== X-IronPort-AV: E=Sophos;i="5.82,272,1613462400"; d="scan'208";a="468436248" Received: from aburakov-mobl.ger.corp.intel.com (HELO [10.213.243.183]) ([10.213.243.183]) by orsmga001-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 04 May 2021 02:32:30 -0700 To: Thomas Monjalon , Conor Walsh Cc: john.mcnamara@intel.com, david.marchand@redhat.com, ferruh.yigit@intel.com, bruce.richardson@intel.com, dev@dpdk.org References: <20210421091146.1384708-1-conor.walsh@intel.com> <2242028.kHp4AaGxEa@thomas> From: "Burakov, Anatoly" Message-ID: Date: Tue, 4 May 2021 10:32:26 +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: <2242028.kHp4AaGxEa@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 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. -- Thanks, Anatoly