nilfs2: correct return value kernel-doc descriptions for metadata files

+20 -31

fs/nilfs2/cpfile.c

··· 191 191 * @cnop: place to store the next checkpoint number 192 192 * @bhp: place to store a pointer to buffer_head struct 193 193 * 194 - * Return Value: On success, it returns 0. On error, the following negative 195 - * error code is returned. 196 - * 197 - * %-ENOMEM - Insufficient memory available. 198 - * 199 - * %-EIO - I/O error 200 - * 201 - * %-ENOENT - no block exists in the range. 194 + * Return: 0 on success, or one of the following negative error codes on 195 + * failure: 196 + * * %-EIO - I/O error (including metadata corruption). 197 + * * %-ENOENT - no block exists in the range. 198 + * * %-ENOMEM - Insufficient memory available. 202 199 */ 203 200 static int nilfs_cpfile_find_checkpoint_block(struct inode *cpfile, 204 201 __u64 start_cno, __u64 end_cno, ··· 444 447 * the period from @start to @end, excluding @end itself. The checkpoints 445 448 * which have been already deleted are ignored. 446 449 * 447 - * Return Value: On success, 0 is returned. On error, one of the following 448 - * negative error codes is returned. 449 - * 450 - * %-EIO - I/O error. 451 - * 452 - * %-ENOMEM - Insufficient amount of memory available. 453 - * 454 - * %-EINVAL - invalid checkpoints. 450 + * Return: 0 on success, or one of the following negative error codes on 451 + * failure: 452 + * * %-EINVAL - Invalid checkpoints. 453 + * * %-EIO - I/O error (including metadata corruption). 454 + * * %-ENOMEM - Insufficient memory available. 455 455 */ 456 456 int nilfs_cpfile_delete_checkpoints(struct inode *cpfile, 457 457 __u64 start, ··· 1052 1058 * Description: nilfs_change_cpmode() changes the mode of the checkpoint 1053 1059 * specified by @cno. The mode @mode is NILFS_CHECKPOINT or NILFS_SNAPSHOT. 1054 1060 * 1055 - * Return Value: On success, 0 is returned. On error, one of the following 1056 - * negative error codes is returned. 1057 - * 1058 - * %-EIO - I/O error. 1059 - * 1060 - * %-ENOMEM - Insufficient amount of memory available. 1061 - * 1062 - * %-ENOENT - No such checkpoint. 1061 + * Return: 0 on success, or one of the following negative error codes on 1062 + * failure: 1063 + * * %-EIO - I/O error (including metadata corruption). 1064 + * * %-ENOENT - No such checkpoint. 1065 + * * %-ENOMEM - Insufficient memory available. 1063 1066 */ 1064 1067 int nilfs_cpfile_change_cpmode(struct inode *cpfile, __u64 cno, int mode) 1065 1068 { ··· 1088 1097 * @cpstat: pointer to a structure of checkpoint statistics 1089 1098 * 1090 1099 * Description: nilfs_cpfile_get_stat() returns information about checkpoints. 1100 + * The checkpoint statistics are stored in the location pointed to by @cpstat. 1091 1101 * 1092 - * Return Value: On success, 0 is returned, and checkpoints information is 1093 - * stored in the place pointed by @cpstat. On error, one of the following 1094 - * negative error codes is returned. 1095 - * 1096 - * %-EIO - I/O error. 1097 - * 1098 - * %-ENOMEM - Insufficient amount of memory available. 1102 + * Return: 0 on success, or one of the following negative error codes on 1103 + * failure: 1104 + * * %-EIO - I/O error (including metadata corruption). 1105 + * * %-ENOMEM - Insufficient memory available. 1099 1106 */ 1100 1107 int nilfs_cpfile_get_stat(struct inode *cpfile, struct nilfs_cpstat *cpstat) 1101 1108 {

+16 -24

fs/nilfs2/dat.c

··· 302 302 * Description: nilfs_dat_freev() frees the virtual block numbers specified by 303 303 * @vblocknrs and @nitems. 304 304 * 305 - * Return Value: On success, 0 is returned. On error, one of the following 306 - * negative error codes is returned. 307 - * 308 - * %-EIO - I/O error. 309 - * 310 - * %-ENOMEM - Insufficient amount of memory available. 311 - * 312 - * %-ENOENT - The virtual block number have not been allocated. 305 + * Return: 0 on success, or one of the following negative error codes on 306 + * failure: 307 + * * %-EIO - I/O error (including metadata corruption). 308 + * * %-ENOENT - The virtual block number have not been allocated. 309 + * * %-ENOMEM - Insufficient memory available. 313 310 */ 314 311 int nilfs_dat_freev(struct inode *dat, __u64 *vblocknrs, size_t nitems) 315 312 { ··· 322 325 * Description: nilfs_dat_move() changes the block number associated with 323 326 * @vblocknr to @blocknr. 324 327 * 325 - * Return Value: On success, 0 is returned. On error, one of the following 326 - * negative error codes is returned. 327 - * 328 - * %-EIO - I/O error. 329 - * 330 - * %-ENOMEM - Insufficient amount of memory available. 328 + * Return: 0 on success, or one of the following negative error codes on 329 + * failure: 330 + * * %-EIO - I/O error (including metadata corruption). 331 + * * %-ENOMEM - Insufficient memory available. 331 332 */ 332 333 int nilfs_dat_move(struct inode *dat, __u64 vblocknr, sector_t blocknr) 333 334 { ··· 385 390 * @blocknrp: pointer to a block number 386 391 * 387 392 * Description: nilfs_dat_translate() maps the virtual block number @vblocknr 388 - * to the corresponding block number. 393 + * to the corresponding block number. The block number associated with 394 + * @vblocknr is stored in the place pointed to by @blocknrp. 389 395 * 390 - * Return Value: On success, 0 is returned and the block number associated 391 - * with @vblocknr is stored in the place pointed by @blocknrp. On error, one 392 - * of the following negative error codes is returned. 393 - * 394 - * %-EIO - I/O error. 395 - * 396 - * %-ENOMEM - Insufficient amount of memory available. 397 - * 398 - * %-ENOENT - A block number associated with @vblocknr does not exist. 396 + * Return: 0 on success, or one of the following negative error codes on 397 + * failure: 398 + * * %-EIO - I/O error (including metadata corruption). 399 + * * %-ENOENT - A block number associated with @vblocknr does not exist. 400 + * * %-ENOMEM - Insufficient memory available. 399 401 */ 400 402 int nilfs_dat_translate(struct inode *dat, __u64 vblocknr, sector_t *blocknrp) 401 403 {

+14 -18

fs/nilfs2/ifile.c

··· 38 38 * @out_ino: pointer to a variable to store inode number 39 39 * @out_bh: buffer_head contains newly allocated disk inode 40 40 * 41 - * Return Value: On success, 0 is returned and the newly allocated inode 42 - * number is stored in the place pointed by @ino, and buffer_head pointer 43 - * that contains newly allocated disk inode structure is stored in the 44 - * place pointed by @out_bh 45 - * On error, one of the following negative error codes is returned. 41 + * nilfs_ifile_create_inode() allocates a new inode in the ifile metadata 42 + * file and stores the inode number in the variable pointed to by @out_ino, 43 + * as well as storing the ifile's buffer with the disk inode in the location 44 + * pointed to by @out_bh. 46 45 * 47 - * %-EIO - I/O error. 48 - * 49 - * %-ENOMEM - Insufficient amount of memory available. 50 - * 51 - * %-ENOSPC - No inode left. 46 + * Return: 0 on success, or one of the following negative error codes on 47 + * failure: 48 + * * %-EIO - I/O error (including metadata corruption). 49 + * * %-ENOMEM - Insufficient memory available. 50 + * * %-ENOSPC - No inode left. 52 51 */ 53 52 int nilfs_ifile_create_inode(struct inode *ifile, ino_t *out_ino, 54 53 struct buffer_head **out_bh) ··· 82 83 * @ifile: ifile inode 83 84 * @ino: inode number 84 85 * 85 - * Return Value: On success, 0 is returned. On error, one of the following 86 - * negative error codes is returned. 87 - * 88 - * %-EIO - I/O error. 89 - * 90 - * %-ENOMEM - Insufficient amount of memory available. 91 - * 92 - * %-ENOENT - The inode number @ino have not been allocated. 86 + * Return: 0 on success, or one of the following negative error codes on 87 + * failure: 88 + * * %-EIO - I/O error (including metadata corruption). 89 + * * %-ENOENT - Inode number unallocated. 90 + * * %-ENOMEM - Insufficient memory available. 93 91 */ 94 92 int nilfs_ifile_delete_inode(struct inode *ifile, ino_t ino) 95 93 {

+27 -32

fs/nilfs2/mdt.c

··· 226 226 * @out_bh: output of a pointer to the buffer_head 227 227 * 228 228 * nilfs_mdt_get_block() looks up the specified buffer and tries to create 229 - * a new buffer if @create is not zero. On success, the returned buffer is 230 - * assured to be either existing or formatted using a buffer lock on success. 231 - * @out_bh is substituted only when zero is returned. 229 + * a new buffer if @create is not zero. If (and only if) this function 230 + * succeeds, it stores a pointer to the retrieved buffer head in the location 231 + * pointed to by @out_bh. 232 232 * 233 - * Return Value: On success, it returns 0. On error, the following negative 234 - * error code is returned. 233 + * The retrieved buffer may be either an existing one or a newly allocated one. 234 + * For a newly created buffer, if the callback function argument @init_block 235 + * is non-NULL, the callback will be called with the buffer locked to format 236 + * the block. 235 237 * 236 - * %-ENOMEM - Insufficient memory available. 237 - * 238 - * %-EIO - I/O error 239 - * 240 - * %-ENOENT - the specified block does not exist (hole block) 241 - * 242 - * %-EROFS - Read only filesystem (for create mode) 238 + * Return: 0 on success, or one of the following negative error codes on 239 + * failure: 240 + * * %-EIO - I/O error (including metadata corruption). 241 + * * %-ENOENT - The specified block does not exist (hole block). 242 + * * %-ENOMEM - Insufficient memory available. 243 + * * %-EROFS - Read only filesystem (for create mode). 243 244 */ 244 245 int nilfs_mdt_get_block(struct inode *inode, unsigned long blkoff, int create, 245 246 void (*init_block)(struct inode *, ··· 276 275 * @out_bh, and block offset to @blkoff, respectively. @out_bh and 277 276 * @blkoff are substituted only when zero is returned. 278 277 * 279 - * Return Value: On success, it returns 0. On error, the following negative 280 - * error code is returned. 281 - * 282 - * %-ENOMEM - Insufficient memory available. 283 - * 284 - * %-EIO - I/O error 285 - * 286 - * %-ENOENT - no block was found in the range 278 + * Return: 0 on success, or one of the following negative error codes on 279 + * failure: 280 + * * %-EIO - I/O error (including metadata corruption). 281 + * * %-ENOENT - No block was found in the range. 282 + * * %-ENOMEM - Insufficient memory available. 287 283 */ 288 284 int nilfs_mdt_find_block(struct inode *inode, unsigned long start, 289 285 unsigned long end, unsigned long *blkoff, ··· 319 321 * @inode: inode of the meta data file 320 322 * @block: block offset 321 323 * 322 - * Return Value: On success, zero is returned. 323 - * On error, one of the following negative error code is returned. 324 - * 325 - * %-ENOMEM - Insufficient memory available. 326 - * 327 - * %-EIO - I/O error 324 + * Return: 0 on success, or one of the following negative error codes on 325 + * failure: 326 + * * %-EIO - I/O error (including metadata corruption). 327 + * * %-ENOENT - Non-existent block. 328 + * * %-ENOMEM - Insufficient memory available. 328 329 */ 329 330 int nilfs_mdt_delete_block(struct inode *inode, unsigned long block) 330 331 { ··· 346 349 * nilfs_mdt_forget_block() clears a dirty flag of the specified buffer, and 347 350 * tries to release the page including the buffer from a page cache. 348 351 * 349 - * Return Value: On success, 0 is returned. On error, one of the following 350 - * negative error code is returned. 351 - * 352 - * %-EBUSY - page has an active buffer. 353 - * 354 - * %-ENOENT - page cache has no page addressed by the offset. 352 + * Return: 0 on success, or one of the following negative error codes on 353 + * failure: 354 + * * %-EBUSY - Page has an active buffer. 355 + * * %-ENOENT - Page cache has no page addressed by the offset. 355 356 */ 356 357 int nilfs_mdt_forget_block(struct inode *inode, unsigned long block) 357 358 {

Configure Feed

Configure Feed