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:   Wed, 22 Jun 2022 10:31:45 -0700
From:   Ira Weiny <ira.weiny@intel.com>
To:     Bagas Sanjaya <bagasdotme@gmail.com>
CC:     <linux-doc@vger.kernel.org>,
        Andrew Morton <akpm@linux-foundation.org>,
        "Matthew Wilcox (Oracle)" <willy@infradead.org>,
        "Fabio M. De Francesco" <fmdefrancesco@gmail.com>,
        Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
        <linux-mm@kvack.org>, <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH v4] Documentation: highmem: Use literal block for code
 example in highmem.h comment
Message-ID: <YrNSASPBivsb60qu@iweiny-desk3>
References: <20220622084546.17745-1-bagasdotme@gmail.com>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <20220622084546.17745-1-bagasdotme@gmail.com>
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?v99ZMEtEg2S6EssECUEH1HfmLlAd1T9Pd2EamvMJWD4OT7kWYQ0V1EHicWpb?=
 =?us-ascii?Q?qHvH5QAfZcyBU2BjciI3WMWg9YBw4EjbCJ9qzu5BL/w39AgWMe1V+qFk5T6r?=
 =?us-ascii?Q?RUlxQX+oW01eQau704AA1mj7ke+fdtejCYbYinN4FV6Jl1wic5fx8GzYmpS9?=
 =?us-ascii?Q?Xl55jstMJX+TzlqI7qRTLlahZHE+cAtZXlA7tsOG+48mkQdrqPkSqLXc+pXN?=
 =?us-ascii?Q?ufRqxPg3hILuEebZJmtZwLo4/1SOvIiLPLrwhjwb1fKqTWX5pNRu8Ie18z5V?=
 =?us-ascii?Q?/YTmMh4vx0zYqi3bKR/xFcHb2EvRJUDD9UAoH2QIlYa0fAsgaLTdasZMYur0?=
 =?us-ascii?Q?Uk7BAdZgdXyWtobgP3jzpsx0W8EU6JAobSPRXDxO1xkagBn4Pcwsc3sHsBFk?=
 =?us-ascii?Q?+GS5uQ/U/08cZ/kQmcRYC5cOtk/lqKKK5TWYcDbFDarNIEn1I7AWaDROof+3?=
 =?us-ascii?Q?SFXDTKAcCG6fOcjX04mlLBJzP17JlGxpPXBZhZsUAB3BqXfk1Wb1U0rmPo4L?=
 =?us-ascii?Q?+lTSO8XNntQoDU7+Hg5rsSnf3PP5qZr/PBuRfO3+PpvxUQuuMbgjENC4Ex11?=
 =?us-ascii?Q?4hzJfZ1M5eYtsdwhvakVs3TIDHCqwgViVJc7lEcONrr/u00kOJW22agW7N1T?=
 =?us-ascii?Q?p+M+yyu5DrYoQIG8NXaIrM1cMSz536nQ8djZwW/MaYwJXSi5nkXlS0QMRDy4?=
 =?us-ascii?Q?18waAk8uOklTBy5oWu0QJ4yFUVIlgF4VYD+VSDeNcW0QcwKq3/MoQFqIJ0sQ?=
 =?us-ascii?Q?YCR7C1cLNQYUcTnFKHefnZ9lqlKrnab8HJftpz2+AmkCEucIt4CYy0uK3VIE?=
 =?us-ascii?Q?SWXmUUzG/MSuh+CSLrzWfohIcP5JFqi+bSj61SQsDfbVYWREp6XKDTODRbm6?=
 =?us-ascii?Q?Q2qggcI9W4RwFwaMilv1SRdcPEppM0q6RxV2/A25RCYV8OtPpKwaBX/weg8W?=
 =?us-ascii?Q?tvQh8AuoKN8JCOMbo41nwLjCYYlKRkOgINA5xakCyOfzZGuNnxqiARmn/0C4?=
 =?us-ascii?Q?K1ECWMQ/IXUJ6G9ezyc1SpbMXgqR/6PWpKKe3d3x9dsrxsp1kQGRAgPwIIOx?=
 =?us-ascii?Q?9tgtYm3jKBO/g1uou8aUfau+r+POO3OBDin1hwEZ8iWKlsDF854jxHIFh3zT?=
 =?us-ascii?Q?cZI+mEmVx59NF+XviclovJ1sCix4yGXdHsU7K+WRieH4K1154ZvpA4C51ZJc?=
 =?us-ascii?Q?ML9TiewjVahwxP3Y64N25zGNY8FoAfu0Xw2VIwDeYpl9kccgGV+L9iJvsA7X?=
 =?us-ascii?Q?sb46GeYuWuvBxDgFnH0++AaIjpKktnVlhJoO6TLAowB+gXrw/qofojch/7jc?=
 =?us-ascii?Q?7MNEHfS8OfRx/tkyGzD/W5so4ftK+9qkEjJ1pdDegPmRkYJUpcpc2pF7EVXj?=
 =?us-ascii?Q?bIneKOaQzCWlTbGXP9JJx8+uTcieCoE8ynxjhyfY0T8ruNHn9wKjQLpoRIkL?=
 =?us-ascii?Q?uaAWDk4BnmjRjftZkiZNhNofxDGpEvNpW4wd1Krvh+e4Sulovjw4bcycY59x?=
 =?us-ascii?Q?IzvYw+itT4aolEyCwAuBJ7KkKYrNzWJ6xbAnuBrw83IjG2sFkSM0FJq6djKh?=
 =?us-ascii?Q?vfIO23s1mn5aIYI6u/AvlJdta9FRS0CYxCT1E+VaVFM+1p6M9vlCk797AR7M?=
 =?us-ascii?Q?1bf8c2dCBdBrPTZ51H8ScEi3VTp9i3Wve/2BUkKo6MPllGccWiG/cuYB9sRi?=
 =?us-ascii?Q?+3jZfK7Fk8CF7/0kPJPpdD3VBvJp3aBoOVE5ufpcYHAaR6ueZ2cYsVIKHAl/?=
 =?us-ascii?Q?UCD6Sl+8RMmbUNI7Bfq2x0kA9SE77sQ=3D?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 3bbd575d-5ca7-4d96-0629-08da547516e0
X-MS-Exchange-CrossTenant-AuthSource: DM4PR11MB6311.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 22 Jun 2022 17:31:49.8971
 (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: E7Hv4xF2UBvZDVdu78iKawVx1VQROj1gzIC5YV/1aZZeb19cU4bWOEHJ9faGCrRVX4RQCzynIGNzwdBg547ihg==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY4PR11MB0070
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,
        RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,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, Jun 22, 2022 at 03:45:46PM +0700, Bagas Sanjaya wrote:
> When building htmldocs on Linus' tree, there are inline emphasis warnings
> on include/linux/highmem.h:
> 
> Documentation/vm/highmem:166: ./include/linux/highmem.h:154: WARNING: Inline emphasis start-string without end-string.
> Documentation/vm/highmem:166: ./include/linux/highmem.h:157: WARNING: Inline emphasis start-string without end-string.
> 
> These warnings above are due to comments in code example at the
> mentioned lines above are enclosed by double dash (--), which confuses
> Sphinx as inline markup delimiters instead.
> 
> Fix these warnings by indenting the code example with literal block
> indentation and making the comments C comments.
> 
> Fixes: 85a85e7601263f ("Documentation/vm: move "Using kmap-atomic" to highmem.h")
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: Ira Weiny <ira.weiny@intel.com>

Thanks!

Reviewed-by: Ira Weiny <ira.weiny@intel.com>
Tested-by: Ira Weiny <ira.weiny@intel.com>

> Cc: "Matthew Wilcox (Oracle)" <willy@infradead.org>
> Cc: "Fabio M. De Francesco" <fmdefrancesco@gmail.com>
> Cc: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> Cc: linux-mm@kvack.org
> Cc: linux-kernel@vger.kernel.org
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Changes since v3 [1]:
>    - Say "C comments" rephrase (suggested by Ira)
> 
>  [1]: https://lore.kernel.org/linux-doc/20220620083649.18172-1-bagasdotme@gmail.com/
> 
>  include/linux/highmem.h | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
> 
> diff --git a/include/linux/highmem.h b/include/linux/highmem.h
> index 3af34de54330cb..56d6a019653489 100644
> --- a/include/linux/highmem.h
> +++ b/include/linux/highmem.h
> @@ -149,19 +149,19 @@ static inline void *kmap_local_folio(struct folio *folio, size_t offset);
>   * It is used in atomic context when code wants to access the contents of a
>   * page that might be allocated from high memory (see __GFP_HIGHMEM), for
>   * example a page in the pagecache.  The API has two functions, and they
> - * can be used in a manner similar to the following:
> + * can be used in a manner similar to the following::
>   *
> - * -- Find the page of interest. --
> - * struct page *page = find_get_page(mapping, offset);
> + *   // Find the page of interest.
> + *   struct page *page = find_get_page(mapping, offset);
>   *
> - * -- Gain access to the contents of that page. --
> - * void *vaddr = kmap_atomic(page);
> + *   // Gain access to the contents of that page.
> + *   void *vaddr = kmap_atomic(page);
>   *
> - * -- Do something to the contents of that page. --
> - * memset(vaddr, 0, PAGE_SIZE);
> + *   // Do something to the contents of that page.
> + *   memset(vaddr, 0, PAGE_SIZE);
>   *
> - * -- Unmap that page. --
> - * kunmap_atomic(vaddr);
> + *   // Unmap that page.
> + *   kunmap_atomic(vaddr);
>   *
>   * Note that the kunmap_atomic() call takes the result of the kmap_atomic()
>   * call, not the argument.
> 
> base-commit: a111daf0c53ae91e71fd2bfe7497862d14132e3e
> -- 
> An old man doll... just what I always wanted! - Clara
>