Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   "Tobin C. Harding" <tobin@kernel.org>
To:     Al Viro <viro@zeniv.linux.org.uk>
Cc:     "Tobin C. Harding" <tobin@kernel.org>,
        Jonathan Corbet <corbet@lwn.net>,
        Mauro Carvalho Chehab <mchehab@s-opensource.com>,
        Neil Brown <neilb@suse.com>,
        Randy Dunlap <rdunlap@infradead.org>,
        linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org,
        linux-kernel@vger.kernel.org
Subject: [PATCH v3 04/24] fs: Add docstrings to exported functions
Date:   Wed, 27 Mar 2019 16:16:57 +1100
Message-Id: <20190327051717.23225-5-tobin@kernel.org>
In-Reply-To: <20190327051717.23225-1-tobin@kernel.org>
References: <20190327051717.23225-1-tobin@kernel.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Currently exported docstrings for fs/file_table.c are included in
Documentation/filesystems/api-summary.rst.  This is a problem because
there are no docstrings in file_table.c

Add function docstrings for exported functions defined in
fs/file_table.c

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 fs/file_table.c | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/fs/file_table.c b/fs/file_table.c
index 5679e7fcb6b0..e3c6966c2d53 100644
--- a/fs/file_table.c
+++ b/fs/file_table.c
@@ -65,8 +65,8 @@ static long get_nr_files(void)
 	return percpu_counter_read_positive(&nr_files);
 }
 
-/*
- * Return the maximum number of open files in the system
+/**
+ * get_max_files() - Get the maximum number of open files in the system.
  */
 unsigned long get_max_files(void)
 {
@@ -178,8 +178,7 @@ struct file *alloc_empty_file_noaccount(int flags, const struct cred *cred)
 }
 
 /**
- * alloc_file - allocate and initialize a 'struct file'
- *
+ * alloc_file() - Allocate and initialize a &struct file.
  * @path: the (dentry, vfsmount) pair for the new file
  * @flags: O_... flags with which the new file will be opened
  * @fop: the 'struct file_operations' for the new file
@@ -210,6 +209,20 @@ static struct file *alloc_file(const struct path *path, int flags,
 	return file;
 }
 
+/**
+ * alloc_file_pseudo() - Allocate a pseudo file.
+ * @inode: The inode to fill in.
+ * @mnt: The vfsmount to use.
+ * @name: Name to used for newly allocated pseudo dentry.
+ * @flags: ``O_...`` flags with which the new file will be opened.
+ * @fops: fops for the new file.
+ *
+ * Allocate a pseudo dentry, fill in @inode information in the dentry
+ * (i.e. instantiate @inode).  Create a &struct path from the dentry and
+ * @mnt.  Allocate a &struct file from the newly created path.
+ *
+ * Return: The newly allocated file or -ENOMEM on error.
+ */
 struct file *alloc_file_pseudo(struct inode *inode, struct vfsmount *mnt,
 				const char *name, int flags,
 				const struct file_operations *fops)
-- 
2.21.0