Hawkmoth & kernel-doc

[Matthew Wilcox <willy@infradead.org>]

I really dislike the javadoc style, so at Jani's urging I gave Hawkmoth
a try.  It's a little fiddly and a little buggy, but I think it
encourages better-written documentation.

I chose mm_inline.h as my victim.  It isn't currently included in the
documentation, and it only has three kernel-doc comments in it to
convert.

I'm approximating what firefox displays here ...

int page_is_file_lru(struct page *page)

  Should the page be on a file LRU or anon LRU?

    Parameters:  * page – The page to test.

    We would like to get this info without a page flag, but the state
    needs to survive until the page is last deleted from the LRU, which
    could be as far down as __page_cache_release.

    Returns:

             An integer (not a boolean!) used to sort a page onto the right
             LRU list and to account folios correctly.

             * 1 if @page is a regular filesystem backed page cache page or a lazily freed anonymous page (e.g. via MADV_FREE).
             * 0 if @page is a normal anonymous page, a tmpfs page or otherwise ram or swap backed page.

That's not _bad_.

1. 'Parameters' is indented further than kernel-doc does (2 levels of
   indent, rather than 0)

2. Output:
<dd><p>Should the page be on a file LRU or anon LRU?</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>page</strong> – The page to test.</p></li>
</ul>
</dd>
</dl>
having gone to the trouble of using a <dl>, I feel that each parameter
should be a <dt> and its definition a <dd>.  That seems to be what
kernel-doc is doing.

3. kernel-doc includes the type of the parameter in the definition,
   while hawkmoth drops it.  I'm ambivalent about which is better.

4. It seems that the indentation of the 'Returns:' paragraph is a bit
   too deep, but it did get the list correct.

5. The second and third functions documented by hawkmoth lose their
   parameter in the initial heading:


int __clear_page_lru_flags()

    Clear page lru flags before releasing a page.

    Parameters  * page – The page that was on lru and now has a zero reference

That first line really should have a 'struct page *page' in it.

6. There's also a warning from the build:

/home/willy/kernel/linux/Documentation/core-api/mm-api.rst:101: WARNING: /home/willy/kernel/linux/include/linux/mm_inline.h:5: 'linux/huge_mm.h' file not found

Looks like I can probably pass arbitrary flags to clang to get it to
find that file, but I'm not sure whether I should.

Here's the diff against current Linus tree that I'm working with:

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7d92ec3e5b6e..13fcce3ec18d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -39,7 +39,7 @@ needs_sphinx = '1.7'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat', 'hawkmoth']
 
 if major >= 3:
     if (major > 3) or (minor > 0 or patch >= 2):
@@ -104,6 +104,7 @@ if major >= 3:
 else:
     extensions.append('cdomain')
 
+cautodoc_root = os.path.abspath('..')
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
index adabb5c5798a..b724e29772b0 100644
--- a/Documentation/core-api/mm-api.rst
+++ b/Documentation/core-api/mm-api.rst
@@ -98,4 +98,5 @@ More Memory Management Functions
    :internal:
 .. kernel-doc:: include/linux/mm.h
    :internal:
+.. c:autodoc:: include/linux/mm_inline.h
 .. kernel-doc:: include/linux/mmzone.h
diff --git a/include/linux/mm_inline.h b/include/linux/mm_inline.h
index 355ea1ee32bd..7db1193a0d94 100644
--- a/include/linux/mm_inline.h
+++ b/include/linux/mm_inline.h
@@ -6,18 +6,21 @@
 #include <linux/swap.h>
 
 /**
- * page_is_file_lru - should the page be on a file LRU or anon LRU?
- * @page: the page to test
+ * Should the page be on a file LRU or anon LRU?
  *
- * Returns 1 if @page is a regular filesystem backed page cache page or a lazily
- * freed anonymous page (e.g. via MADV_FREE).  Returns 0 if @page is a normal
- * anonymous page, a tmpfs page or otherwise ram or swap backed page.  Used by
- * functions that manipulate the LRU lists, to sort a page onto the right LRU
- * list.
+ * :param page: The page to test.
  *
  * We would like to get this info without a page flag, but the state
  * needs to survive until the page is last deleted from the LRU, which
  * could be as far down as __page_cache_release.
+ *
+ * :return: An integer (not a boolean!) used to sort a page onto the right
+ *   LRU list and to account folios correctly.
+ *
+ *   - 1 if @page is a regular filesystem backed page cache page or a lazily
+ *     freed anonymous page (e.g. via MADV_FREE).
+ *   - 0 if @page is a normal anonymous page, a tmpfs page or otherwise ram or
+ *     swap backed page.
  */
 static inline int page_is_file_lru(struct page *page)
 {
@@ -39,8 +42,9 @@ static __always_inline void update_lru_size(struct lruvec *lruvec,
 }
 
 /**
- * __clear_page_lru_flags - clear page lru flags before releasing a page
- * @page: the page that was on lru and now has a zero reference
+ * Clear page lru flags before releasing a page.
+ *
+ * :param page: The page that was on lru and now has a zero reference
  */
 static __always_inline void __clear_page_lru_flags(struct page *page)
 {
@@ -57,11 +61,12 @@ static __always_inline void __clear_page_lru_flags(struct page *page)
 }
 
 /**
- * page_lru - which LRU list should a page be on?
- * @page: the page to test
+ * Which LRU list should a page be on?
+ *
+ * :param page: The page to test
  *
- * Returns the LRU list a page should be on, as an index
- * into the array of LRU lists.
+ * :return: The LRU list a page should be on, as an index into the array
+ *          of LRU lists.
  */
 static __always_inline enum lru_list page_lru(struct page *page)
 {