Date:   Thu, 28 Apr 2022 23:24:51 +0200
From:   "Fabio M. De Francesco" <fmdefrancesco@...il.com>
To:     Ira Weiny <ira.weiny@...el.com>,
        Andrew Morton <akpm@...ux-foundation.org>,
        Catalin Marinas <catalin.marinas@....com>,
        "Matthew Wilcox (Oracle)" <willy@...radead.org>,
        Will Deacon <will@...nel.org>,
        Peter Collingbourne <pcc@...gle.com>,
        Vlastimil Babka <vbabka@...e.cz>,
        Sebastian Andrzej Siewior <bigeasy@...utronix.de>,
        linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org,
        outreachy@...ts.linux.dev
Cc:     "Fabio M. De Francesco" <fmdefrancesco@...il.com>
Subject: [PATCH v4 0/4] Extend and reorganize Highmem's documentation

This series has the purpose to extend and reorganize Highmem's
documentation.

This is a work in progress because some information should still be moved
from highmem.rst to highmem.h and highmem-internal.h. Specifically I'm
talking about moving the "how to" information to the relevant headers, as
it as been suggested by Ira Weiny (Intel).

Also, this is a work in progress because some kdocs in highmem.h and
highmem-internal.h should be improved.

However, I think (and hope that my thoughts are also shared by Maintainers
and Reviewers) that this series constitues a sensible step forward
improving Highmem's documentation, despite some important issues are not
yet addressed.

Changes from v1 to v2:

        1/4 - Fix typos (Mike Rapoport); re-write the description of @page
              because the original was wrong (Ira Weiny); add Ira's and
              Mike's tags in the commit message.
        2/4 - Add Ira's and Mike's tags in the commit message.
        3/4 - Rework the subject to better summarize what this patch
              changes; merge the section which was removed from highmem.rst
              with the kdocs of highmem.h (suggested by Ira Weiny); add
              Ira's tag in the commit message.
        4/4 - Reformulate a sentence that was incomprehensible due to my
              own mistakes in copying and pasting the text of another
              paragraph (problem noted by Ira Weiny); refer to the kdocs
              of kmap_local_page () to show how nested mappings should be
              handled; fix grammar error; add Ira's tag in the commit
              message.

Changes from v2 to v3:

        1/4 - Add a deprecation notice to kunmap_atomic() for consistency
              with the same notice in kmap_atomic() (Sebastian Andrzej
              Siewior); shorten subject and extend commit message.
        2/4 - No changes.
        3/4 - No changes.
        4/4 - Correct a technical inaccuracy about preemption disabling /
              re-enabling in kmap_atomic() / kunmap_atomic() (Sebastian
              Andrzej Siewior).

Changes from v3 to v4:

	1/4 - Correct some techinal inaccuracies about the side effects
	      of calling kmap_atomic() and kmap_local_page() (Sebastian
	      Andrzej Siewior); drop "Acked-by:" and "Reviewed-by:" tags
	      because relevant parts of this patch have changed.
	2/4 - No changes.
	3/4 - No changes.
	4/4 - Shorten a couple of paragraphs by removing redundant
	      information (Sebastian Andrzej Siewior).

Fabio M. De Francesco (4):
  mm/highmem: Fix kernel-doc warnings in highmem*.h
  Documentation/vm: Include kdocs from highmem*.h into highmem.rst
  Documentation/vm: Move "Using kmap-atomic" from highmem.rst to
    highmem.h
  Documentation/vm: Rework "Temporary Virtual Mappings" section

 Documentation/vm/highmem.rst     | 100 ++++++++++++++++++-------------
 include/linux/highmem-internal.h |  18 +++++-
 include/linux/highmem.h          |  51 ++++++++++++----
 3 files changed, 113 insertions(+), 56 deletions(-)

-- 
2.34.1

Powered by blists - more mailing lists