Commit c551f66c authored by Lee Jones's avatar Lee Jones Committed by Andreas Gruenbacher
Browse files

gfs2: Fix a number of kernel-doc warnings 



Building the kernel with W=1 results in a number of kernel-doc warnings
like incorrect function names and parameter descriptions.  Fix those,
mostly by adding missing parameter descriptions, removing left-over
descriptions, and demoting some less important kernel-doc comments into
regular comments.

Originally proposed by Lee Jones; improved and combined into a single
patch by Andreas.

Signed-off-by: default avatarLee Jones <lee.jones@linaro.org>
Signed-off-by: default avatarAndreas Gruenbacher <agruenba@redhat.com>
parent a4122a95

fs/gfs2/aops.c

+1 −4
Original line number Diff line number Diff line
@@ -540,10 +540,7 @@ int gfs2_internal_read(struct gfs2_inode *ip, char *buf, loff_t *pos, 


/**

 * gfs2_readahead - Read a bunch of pages at once

 * @file: The file to read from

 * @mapping: Address space info

 * @pages: List of pages to read

 * @nr_pages: Number of pages to read

 * @rac: Read-ahead control structure

 *

 * Some notes:

 * 1. This is only for readahead, so we can simply ignore any things

fs/gfs2/bmap.c

+4 −1
Original line number Diff line number Diff line
@@ -1479,7 +1479,7 @@ int gfs2_iomap_alloc(struct inode *inode, loff_t pos, loff_t length, 
/**

 * sweep_bh_for_rgrps - find an rgrp in a meta buffer and free blocks therein

 * @ip: inode

 * @rg_gh: holder of resource group glock

 * @rd_gh: holder of resource group glock

 * @bh: buffer head to sweep

 * @start: starting point in bh

 * @end: end point in bh
@@ -1660,8 +1660,11 @@ static bool mp_eq_to_hgt(struct metapath *mp, __u16 *list, unsigned int h) 


/**

 * find_nonnull_ptr - find a non-null pointer given a metapath and height

 * @sdp: The superblock

 * @mp: starting metapath

 * @h: desired height to search

 * @end_list: See punch_hole().

 * @end_aligned: See punch_hole().

 *

 * Assumes the metapath is valid (with buffers) out to height h.

 * Returns: true if a non-null pointer was found in the metapath buffer

fs/gfs2/file.c

+3 −4
Original line number Diff line number Diff line
@@ -118,8 +118,8 @@ static int gfs2_readdir(struct file *file, struct dir_context *ctx) 
	return error;

}



/**

 * fsflag_gfs2flag

/*

 * struct fsflag_gfs2flag

 *

 * The FS_JOURNAL_DATA_FL flag maps to GFS2_DIF_INHERIT_JDATA for directories,

 * and to GFS2_DIF_JDATA for non-directories.
@@ -435,7 +435,6 @@ static int gfs2_allocate_page_backing(struct page *page, unsigned int length) 


/**

 * gfs2_page_mkwrite - Make a shared, mmap()ed, page writable

 * @vma: The virtual memory area

 * @vmf: The virtual memory fault containing the page to become writable

 *

 * When the page becomes writable, we need to ensure that we have
@@ -586,7 +585,7 @@ static const struct vm_operations_struct gfs2_vm_ops = { 
};



/**

 * gfs2_mmap -

 * gfs2_mmap

 * @file: The file to map

 * @vma: The VMA which described the mapping

 *

fs/gfs2/glock.c

+6 −4
Original line number Diff line number Diff line
@@ -359,7 +359,8 @@ static void gfs2_holder_wake(struct gfs2_holder *gh) 


/**

 * do_error - Something unexpected has happened during a lock request

 *

 * @gl: The glock

 * @ret: The status from the DLM

 */



static void do_error(struct gfs2_glock *gl, const int ret)
@@ -454,8 +455,7 @@ static inline struct gfs2_holder *find_first_waiter(const struct gfs2_glock *gl) 
/**

 * state_change - record that the glock is now in a different state

 * @gl: the glock

 * @new_state the new state

 *

 * @new_state: the new state

 */



static void state_change(struct gfs2_glock *gl, unsigned int new_state)
@@ -1268,6 +1268,8 @@ int gfs2_glock_async_wait(unsigned int num_gh, struct gfs2_holder *ghs) 
 * handle_callback - process a demote request

 * @gl: the glock

 * @state: the state the caller wants us to change to

 * @delay: zero to demote immediately; otherwise pending demote

 * @remote: true if this came from a different cluster node

 *

 * There are only two requests that we are going to see in actual

 * practise: LM_ST_SHARED and LM_ST_UNLOCKED
@@ -1569,6 +1571,7 @@ static int glock_compare(const void *arg_a, const void *arg_b) 
 * nq_m_sync - synchonously acquire more than one glock in deadlock free order

 * @num_gh: the number of structures

 * @ghs: an array of struct gfs2_holder structures

 * @p: placeholder for the holder structure to pass back

 *

 * Returns: 0 on success (all glocks acquired),

 *          errno on failure (no glocks acquired)
@@ -1985,7 +1988,6 @@ static void dump_glock_func(struct gfs2_glock *gl) 
/**

 * gfs2_gl_hash_clear - Empty out the glock hash table

 * @sdp: the filesystem

 * @wait: wait until it's all gone

 *

 * Called when unmounting the filesystem.

 */

fs/gfs2/glops.c

+5 −9
Original line number Diff line number Diff line
@@ -49,6 +49,7 @@ static void gfs2_ail_error(struct gfs2_glock *gl, const struct buffer_head *bh) 
 * __gfs2_ail_flush - remove all buffers for a given lock from the AIL

 * @gl: the glock

 * @fsync: set when called from fsync (not all buffers will be clean)

 * @nr_revokes: Number of buffers to revoke

 *

 * None of the buffers should be dirty, locked, or pinned.

 */
@@ -474,8 +475,7 @@ int gfs2_inode_refresh(struct gfs2_inode *ip) 


/**

 * inode_go_lock - operation done after an inode lock is locked by a process

 * @gl: the glock

 * @flags:

 * @gh: The glock holder

 *

 * Returns: errno

 */
@@ -516,7 +516,7 @@ static int inode_go_lock(struct gfs2_holder *gh) 
/**

 * inode_go_dump - print information about an inode

 * @seq: The iterator

 * @ip: the inode

 * @gl: The glock

 * @fs_id_buf: file system id (may be empty)

 *

 */
@@ -547,9 +547,6 @@ static void inode_go_dump(struct seq_file *seq, struct gfs2_glock *gl, 
/**

 * freeze_go_sync - promote/demote the freeze glock

 * @gl: the glock

 * @state: the requested state

 * @flags:

 *

 */



static int freeze_go_sync(struct gfs2_glock *gl)
@@ -594,9 +591,7 @@ static int freeze_go_sync(struct gfs2_glock *gl) 
/**

 * freeze_go_xmote_bh - After promoting/demoting the freeze glock

 * @gl: the glock

 *

 */



static int freeze_go_xmote_bh(struct gfs2_glock *gl)

{

	struct gfs2_sbd *sdp = gl->gl_name.ln_sbd;
@@ -624,7 +619,7 @@ static int freeze_go_xmote_bh(struct gfs2_glock *gl) 
}



/**

 * trans_go_demote_ok

 * freeze_go_demote_ok

 * @gl: the glock

 *

 * Always returns 0
@@ -638,6 +633,7 @@ static int freeze_go_demote_ok(const struct gfs2_glock *gl) 
/**

 * iopen_go_callback - schedule the dcache entry for the inode to be deleted

 * @gl: the glock

 * @remote: true if this came from a different cluster node

 *

 * gl_lockref.lock lock is held while calling this

 */