Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Tue, 9 Aug 2022 05:55:10 -0400
From:   Rodrigo Vivi <rodrigo.vivi@intel.com>
To:     Mauro Carvalho Chehab <mchehab@kernel.org>
CC:     David Airlie <airlied@linux.ie>, <intel-gfx@lists.freedesktop.org>,
        <linux-kernel@vger.kernel.org>, <dri-devel@lists.freedesktop.org>
Subject: Re: [Intel-gfx] [PATCH v2 18/39] drm/i915: intel_pm.c: fix some
 ascii artwork at kernel-doc
Message-ID: <YvIu/oCnkDbdLqou@intel.com>
References: <cover.1657699522.git.mchehab@kernel.org>
 <b3657e96ea87a5803ed27d1cc0d9fa44b2f164cf.1657699522.git.mchehab@kernel.org>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <b3657e96ea87a5803ed27d1cc0d9fa44b2f164cf.1657699522.git.mchehab@kernel.org>
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?91YRN0UbT493bRknOyLGzz2iFJXd8QnPtWgS2jrmM7YxKp6DwKOZVHVYFewE?=
 =?us-ascii?Q?t55/16S5bwB2UtHU2Nt0wfB+x3URzNfzkcyMGapFeYfGGOZJ9gfPV0hdq/yK?=
 =?us-ascii?Q?1xLjgy+PD34pM/l0hJiFj2I9T7/foa+P8sB77/ajDU5mSn3g0e08wOb5XAFv?=
 =?us-ascii?Q?bTvYJRyfTVFjEb1+NpVD/0Vh1xHjFI/7Ij+8AYWGFab54y8oKJB2AuQlOZVY?=
 =?us-ascii?Q?m27+7UI3Aa/FacyPsIezlFryMCFCigR0qp/abK6jlGGclsrb25aj62ZYT0/M?=
 =?us-ascii?Q?JVpPPnvR6unubOt9t053EeGZ9TpFBzUFSH0DsbKOWAENUZVC4knds7zO9MPV?=
 =?us-ascii?Q?KBb+h6UTo6LVKi3uxHWHFPJyvMvVKl0cgMnuxIOalpBuCTsJZQEsBx1Bf6vr?=
 =?us-ascii?Q?D/wL02qsnIay2EO0oksBF6G0cQWsr3seurwSRaap0hXl496jwN+gzBnVZnEM?=
 =?us-ascii?Q?YEWkDUUcqNvi07XPYPfQuxe8HOuRvG1jszSGU9/1qlAkQwDxEeDGQaCaX6RG?=
 =?us-ascii?Q?fox0VcTREi1IRlyODZzOu8Lc9Y/nbqPoR0psAit3dZn3BsuDivDuL8DE2L3R?=
 =?us-ascii?Q?9AAuUjStMInL8UlA5wTMlxlUGNreqdheVRZtcRb/Sf7a95AyKusY831Ns+YA?=
 =?us-ascii?Q?j8XKxVrKfVct366EBI6AKIkmIpka+mjCznkr4EfMjofDT8QQ7RD5qPAYBAsD?=
 =?us-ascii?Q?EvNBWOvgA6nKEsewWdqhJUR2sSui6T5MOKRGV+wZSYdPjWtDI6AZVOm6vLjX?=
 =?us-ascii?Q?B7ZI36IoIb5OVDMP2e1VImBzpAB5ws+dL/p6rx7oOhgqSfPmtqt/LWTz/jYl?=
 =?us-ascii?Q?vJBkktBT2dnCbdwBqD0yn4uJMAC+3hOok5/hCJbqTO/+NKYbx6oEcfC6ryno?=
 =?us-ascii?Q?0kdsaPK6ZWyZvRDuWjv8ht9LJqFHw6lx/ktrs4TYCs0gn21M3SZr7mx/3OOh?=
 =?us-ascii?Q?vxxxf1nwy9pjAoz+NF9S3ycQ0CrEmev8YWiQNYbzpzB/xKnuorBoA+fr3jAT?=
 =?us-ascii?Q?walITKRFlfRwT7JpctptpK+ZS6FnfADPZEO6PSZMJQVw02W/QC0DkLmucVKP?=
 =?us-ascii?Q?AMA3l1L5qQC+3YW0SBQocYkveQehgZUYXXKFTNYV8mGQIqPreVI70/uMYn/J?=
 =?us-ascii?Q?NuesYQO29p/S6bfPCyuO8AMFqNsp9SgxxPC3bbYJymlojbhpCUkCWVKKHmXJ?=
 =?us-ascii?Q?OYMy86T75ksAJj436TUaTL+/vC/ce3C1f56O3uOjoTaKSgyujHKYqx6GIgBc?=
 =?us-ascii?Q?22abDy+ilkcs62fEb7rAZAY/36qGazct87RVZZcH1ejkCgB/tCEKgKVNcwgn?=
 =?us-ascii?Q?B4wcFlu0AtddHed4JEhCl9Gw5PazJ5vGEdfTzR8ZTK88O18h3rHL3x8oRH/J?=
 =?us-ascii?Q?WpkCXwd5/puBdwTQ0cXhe3C9e529TPR9InNZKbDhFavVud1XFFVulwJ2Eo5i?=
 =?us-ascii?Q?BNFCiwUSmmQqa6Ca8tnzfV5ve4X1i3/9ltqZdxBxhvruQhA82A4R2UcfAYDB?=
 =?us-ascii?Q?R47tKg/0HIXFDEl2Rd6GfV6FJF4KLr7MZytP5mN1D/etNqcQoC8D6mxIq89+?=
 =?us-ascii?Q?UWQzcj+mmktgl9mA+Y6OXd2YY3Zk54KFVuo1flzEtDioK7ocykNAY9qhvZ7D?=
 =?us-ascii?Q?kQ=3D=3D?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 8b20fa71-fd72-496f-d929-08da79ed41e4
X-MS-Exchange-CrossTenant-AuthSource: MN0PR11MB6059.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 09 Aug 2022 09:55:14.9812
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: b4jqHGLIhD+V+O2BZCcbVcoEmiP0zNcbVPk7k1c5+rCzhsYROkCXCnPnvphmeaMtOaU46p+2S/clSnf2JfpL/A==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ0PR11MB4958
X-OriginatorOrg: intel.com
X-Spam-Status: No, score=-5.0 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,
        DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_MED,
        SPF_HELO_NONE,SPF_NONE,T_SCC_BODY_TEXT_LINE autolearn=ham
        autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Wed, Jul 13, 2022 at 09:12:06AM +0100, Mauro Carvalho Chehab wrote:
> Preserving ascii artwork on kernel-docs is tricky, as it needs
> to respect both the Sphinx rules and be properly parsed by
> kernel-doc script.
> 
> The Sphinx syntax require code-blocks, which is:
> 
> 	::
> 
> followed by a blank line and indented lines.
> 
> But kernel-doc only works fine if the first and the last line
> are indented with the same amount of spaces.
> 
> Also, a "\" at the end means that the next line should be merged
> with the first one.

my first reaction was: "do we really need those new empty ( ) blocks?"

Then I read this ;)

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

> 
> Change the ascii artwork to be on code-blocks, starting all
> lines at the same characters and not ending with a backslash.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/
> 
>  drivers/gpu/drm/i915/intel_pm.c | 33 ++++++++++++++++++---------------
>  1 file changed, 18 insertions(+), 15 deletions(-)
> 
> diff --git a/drivers/gpu/drm/i915/intel_pm.c b/drivers/gpu/drm/i915/intel_pm.c
> index f06babdb3a8c..d3393752b04b 100644
> --- a/drivers/gpu/drm/i915/intel_pm.c
> +++ b/drivers/gpu/drm/i915/intel_pm.c
> @@ -684,18 +684,20 @@ static const struct intel_watermark_params i845_wm_info = {
>   * FIFO is relatively small compared to the amount of data
>   * fetched.
>   *
> - * The FIFO level vs. time graph might look something like:
> + * The FIFO level vs. time graph might look something like::
>   *
> - *   |\   |\
> - *   | \  | \
> - * __---__---__ (- plane active, _ blanking)
> - * -> time
> + *   ^
> + *   |   |\   |\      (                          )
> + *   |   | \  | \     (                          )
> + *   |   __---__---__ (- plane active, _ blanking)
> + *   +-------------------> time
>   *
> - * or perhaps like this:
> + * or perhaps like this::
>   *
> - *   |\|\  |\|\
> - * __----__----__ (- plane active, _ blanking)
> - * -> time
> + *   ^
> + *   |     |\|\  |\|\   (                          )
> + *   |   __----__----__ (- plane active, _ blanking)
> + *   +-------------------> time
>   *
>   * Returns:
>   * The watermark in bytes
> @@ -731,13 +733,14 @@ static unsigned int intel_wm_method1(unsigned int pixel_rate,
>   * FIFO is relatively large compared to the amount of data
>   * fetched.
>   *
> - * The FIFO level vs. time graph might look something like:
> + * The FIFO level vs. time graph might look something like::
>   *
> - *    |\___       |\___
> - *    |    \___   |    \___
> - *    |        \  |        \
> - * __ --__--__--__--__--__--__ (- plane active, _ blanking)
> - * -> time
> + *   ^
> + *   |     |\___       |\___        (                          )
> + *   |     |    \___   |    \___    (                          )
> + *   |     |        \  |        \   (                          )
> + *   |  __ --__--__--__--__--__--__ (- plane active, _ blanking)
> + *   +---------------------------------> time
>   *
>   * Returns:
>   * The watermark in bytes
> -- 
> 2.36.1
>