Improve the documentation of logging_log_file() and logging_log_filetrans().

policy/modules/system/logging.if

@@ -1,15 +1,42 @@
 ## <summary>Policy for the kernel message logger and system logging daemon.</summary>
 
-#######################################
+########################################
 ## <summary>
-##	Make the specified type a file
+##	Make the specified type usable for log files
-##	used for logs.
+##	in a filesystem.
 ## </summary>
-## <param name="file_type">
+## <desc>
+##	<p>
+##	Make the specified type usable for log files in a filesystem.
+##	This will also make the type usable for files, making 
+##	calls to files_type() redundant.  Failure to use this interface
+##	for a log file type may result in problems with log
+##	rotation, log analysis, and log monitoring programs.
+##	</p>
+##	<p>
+##	Related interfaces:
+##	</p>
+##	<ul>
+##		<li>logging_log_filetrans()</li>
+##	</ul>
+##	<p>
+##	Example usage with a domain that can create
+##	and append to a private log file stored in the
+##	general directories (e.g., /var/log):
+##	</p>
+##	<p>
+##	type mylogfile_t;
+##	logging_log_file(mylogfile_t)
+##	allow mydomain_t mylogfile_t:file { create_file_perms append_file_perms };
+##	logging_log_filetrans(mydomain_t, mylogfile_t, file)
+##	</p>
+## </desc>
+## <param name="type">
 ##	<summary>
-##	Type of the file to be used as a log.
+##	Type to be used for files.
 ##	</summary>
 ## </param>
+## <infoflow type="none"/>
 #
 interface(`logging_log_file',`
 	gen_require(`
@@ -395,9 +422,18 @@ interface(`logging_domtrans_syslog',`
 
 ########################################
 ## <summary>
-##	Create an object in the log directory, with a private
+##	Create an object in the log directory, with a private type.
-##	type using a type transition.
 ## </summary>
+## <desc>
+##	<p>
+##	Allow the specified domain to create an object
+##	in the general system log directories (e.g., /var/log)
+##	with a private type.  Typically this is used for creating
+##	private log files in /var/log with the private type instead
+##	of the general system log type. To accomplish this goal,
+##	either the program must be SELinux-aware, or use this interface.
+##	</p>
+## </desc>
 ## <param name="domain">
 ##	<summary>
 ##	Domain allowed access.
@@ -413,6 +449,7 @@ interface(`logging_domtrans_syslog',`
 ##	The object class of the object being created.
 ##	</summary>
 ## </param>
+## <infoflow type="write" weight="10"/>
 #
 interface(`logging_log_filetrans',`
 	gen_require(`