keyctl.2: srcfix: FIXME clean-up

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/keyctl.2

@@ -161,7 +161,7 @@ and the behavior is as follows:
 If a keyring with a matching description exists,
 the process will attempt to subscribe to that keyring if possible;
 if that is not possible, an error is returned.
-.\" FIXME What error is returned?
+.\" FIXME What error is returned in the above case?
 In order to subscribe to the keyring,
 the caller must have
 .I search
@@ -235,8 +235,8 @@ or
 .IR setattr
 permission on the key.
 .\" FIXME Keys with the KEY_FLAG_KEEP bit set cause an EPERM
-.\"       error for KEYCTL_REVOKE. Does this need to be documented?
+.\" error for KEYCTL_REVOKE. Does this need to be documented?
-.\"       (It's not clear how KEY_FLAG_KEEP gets set.)
+.\" (It's not clear how KEY_FLAG_KEEP gets set.)
 
 The arguments
 .IR arg3 ,
@@ -723,8 +723,9 @@ then that link will be displaced by a link to
 the key found by this operation.
 
 Instead of valid existing keyring IDs, the source
-.\" FIXME Is it really true that both of these arguments can be
+.\" FIXME Regarding the next sentence:
-.\"       special key IDs?
+.\" Is it really true that both 'arg2' (keyring to search)
+.\" and 'arg5' (destination keyring) can be special key IDs?
 .RI ( arg2 )
 and destination
 .RI ( arg5 )
@@ -784,8 +785,8 @@ The key must either grant the caller
 .I read
 permission, or grant the caller
 .I search
-.\" FIXME What does the following piece mean?
 permission when searched for from the process keyrings.
+.\" FIXME Above, what does "searched for from the process keyrings" mean?
 
 The
 .I arg5
@@ -797,7 +798,6 @@ via the function
 .BR keyctl_read (3).
 .TP
 .BR KEYCTL_INSTANTIATE " (since Linux 2.6.11)"
-.\" FIXME There's a lot more detail to add here...
 .\" FIXME I added the word "(Positively)" in the next sentence. Okay?
 (Positively) instantiate an uninstantiated key with a specified payload.
 
@@ -817,6 +817,9 @@ the size of that buffer is specified in
 
 The payload may be a NULL pointer and the buffer size may be 0
 if this is supported by the key type.
+.\" FIXME Above, what is an example of a key type that supports a
+.\" a NULL payload plus buffer size of zero? Keyrings?
+
 The operation may be fail if the payload data is in the wrong format
 or is otherwise invalid.
 
@@ -856,10 +859,13 @@ via the function
 .TP
 .BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
 Set the default keyring to which implicitly requested keys
-.\" FIXME What are implcitly requested keys?
+.\" FIXME What are implicitly requested keys?
 .\"
-.\"     The implicit requests make use of the kernel-internal request_key()
+.\" Are implicit requests just the ones that use the kernel-internal
-.\"     function (which is not the same as the request_key(2) system call).
+.\" request_key() function (which is not the same as the request_key(2)
+.\" system call)?
+.\"
+.\" Does this operation have any effect for the request_key(2) system call?
 will be linked for this thread, and return the previous setting.
 Implicit key requests can occur when, for example, opening files
 on an AFS or NFS filesystem.
@@ -872,9 +878,9 @@ should contain one of the following values,
 to specify the new default keyring:
 .RS
 .TP
-.\" FIXME: what is the purpose of KEY_REQKEY_DEFL_NO_CHANGE?
 .BR KEY_REQKEY_DEFL_NO_CHANGE
 No change.
+.\" FIXME: What is the purpose of KEY_REQKEY_DEFL_NO_CHANGE?
 .TP
 .BR KEY_REQKEY_DEFL_DEFAULT
 This selects the default behaviour,
@@ -911,8 +917,8 @@ as the new default keyring.
 .TP
 .BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
 '\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
-.\" FIXME The following needs to be expanded.
 Use the requestor keyring.
+.\" FIXME The preceding explanation needs to be expanded.
 .RE
 .IP
 All other values are invalid.
@@ -937,10 +943,11 @@ via the function
 .TP
 .BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
 .\" FIXME Against which clock is the timeout measured?
-.\"       (It looks to be the REALTIME clock)
+.\" (It looks to be the REALTIME clock; was there a particular reason to
-.\" FIXME Other than looking in /proc/keys, is there any way of
+.\" choose the REALTIME clock over the MONOTONIC clock?)
-.\"       discovering the timeout on a key?
 Set a timeout on a key.
+.\" FIXME Other than looking in /proc/keys, is there any way of
+.\" discovering the timeout on a key?
 
 The ID of the key is specified in
 .I arg2
@@ -1498,8 +1505,8 @@ for keyrings to be exceeded.
 .TP
 .B ENFILE
 .\" FIXME Does this error really occur? I could not find where
-.\"       in the kernel source it is generated, but have not tested
+.\" in the kernel source it is generated, but have not tested
-.\"       this case from a user-space program
+.\" this case from a user-space program
 .IR operation
 is
 .BR KEYCTL_LINK