Re: [PATCH v5 1/1] docs/mm: Physical Memory: add structure, introduction and nodes description

[Jonathan Corbet]

Mike Rapoport <rppt@xxxxxxxxxx> writes:

> From: "Mike Rapoport (IBM)" <rppt@xxxxxxxxxx>
>
> Add structure, introduction and Nodes section to Physical Memory
> chapter.
>
> As the new documentation references core-api/dma-api and mm/page_reclaim,
> add page labels to those documents.
>
> Reviewed-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
> Reviewed-by: Lorenzo Stoakes <lstoakes@xxxxxxxxx>
> Acked-by: Michal Hocko <mhocko@xxxxxxxx>
> Acked-by: Vlastimil Babka <vbabka@xxxxxxx>
> Signed-off-by: Mike Rapoport (IBM) <rppt@xxxxxxxxxx>

I've gone ahead and applied this, but I do have one little gripe...

>  Documentation/core-api/dma-api.rst   |   2 +
>  Documentation/mm/page_reclaim.rst    |   2 +
>  Documentation/mm/physical_memory.rst | 347 +++++++++++++++++++++++++++
>  3 files changed, 351 insertions(+)
>
> diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
> index 829f20a193ca..c847a5b0a0d3 100644
> --- a/Documentation/core-api/dma-api.rst
> +++ b/Documentation/core-api/dma-api.rst
> @@ -1,3 +1,5 @@
> +.. _dma_api:
> +

Top-of-file labels like this one...

>  ============================================
>  Dynamic DMA mapping using the generic device
>  ============================================
> diff --git a/Documentation/mm/page_reclaim.rst b/Documentation/mm/page_reclaim.rst
> index 50a30b7f8ac3..3fccde066436 100644
> --- a/Documentation/mm/page_reclaim.rst
> +++ b/Documentation/mm/page_reclaim.rst
> @@ -1,5 +1,7 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> +.. _page_reclaim:

...and this one really just add noise without bringing any value.
Something like:

> +Reclaim control
> +~~~~~~~~~~~~~~~
> +
> +See also :ref:`Page Reclaim <page_reclaim>`.

Can also just be "See also Documentation/mm/page_reclaim.rst".  The
right things will happen in the HTML output, readers of the plain-text
will know immediately where to go, and we don't have to add the label
clutter.

</gripe> :)

Thanks,

jon