Add support for marking a function as deprecated or experimental.

git-svn-id: svn+ssh://svn.openpam.org/svn/openpam/trunk@596 185d5e19-27fe-0310-9dcf-9bff6b9f3609

lib/openpam_get_feature.c

@@ -63,18 +63,21 @@ openpam_get_feature(int feature, int *onoff)
  */
 
 /**
+ * EXPERIMENTAL
+ *
  * The =openpam_get_feature function stores the current state of the
  * specified feature in the variable pointed to by its =onoff argument.
  *
  * The following features are recognized:
  *
  *	=OPENPAM_FEATURE_RESTRICT_SERVICE_NAME:
- 
- *		Restrict service names to sequences of characters from the
+ *		Disallow path separators in service names.
+ *		Disabling this feature allows the application
+ Restrict service names to sequences of characters from the
  *		POSIX portable filename character set, not including the
  *		path separator.
  
- *		If this feature is disabled, the service name parameter
+ *		If this feature is disabled, the application can specifyservice name parameter
  *		can be used to specify a policy file directly.
  
  *		This feature is enabled by default.

lib/openpam_readline.c

@@ -111,6 +111,8 @@ fail:
 }
 
 /**
+ * DEPRECATED openpam_readlinev
+ *
  * The =openpam_readline function reads a line from a file, and returns it
  * in a NUL-terminated buffer allocated with =!malloc.
  *

lib/openpam_set_feature.c

@@ -63,7 +63,11 @@ openpam_set_feature(int feature, int onoff)
  */
 
 /**
- * The =openpam_set_feature function
+ * EXPERIMENTAL
+ *
+ * The =openpam_set_feature function sets the state of the specified
+ * feature to the value specified by the =onoff argument.
+ * See =openpam_get_feature for a list of recognized features.
  *
  * >openpam_get_feature
  *

misc/gendoc.pl

@@ -140,6 +140,8 @@ sub parse_source($) {
     my $intaglist;
     my $inliteral;
     my $customrv;
+    my $deprecated;
+    my $experimental;
     my %xref;
     my @errors;
     my $author;
@@ -158,10 +160,18 @@ sub parse_source($) {
 	if ($source =~ m/^ \* NOPARSE\s*$/m);
 
     $author = 'THINKSEC';
-    if ($source =~ s/^ \* AUTHOR\s+(.*?)\s*$//m) {
+    if ($source =~ s/^ \* AUTHOR\s+(\w*)\s*$//m) {
 	$author = $1;
     }
 
+    if ($source =~ s/^ \* DEPRECATED\s*(\w*)\s*$//m) {
+	$deprecated = $1 // 0;
+    }
+
+    if ($source =~ s/^ \* EXPERIMENTAL\s*$//m) {
+	$experimental = 1;
+    }
+
     $func = $fn;
     $func =~ s,^(?:.*/)?([^/]+)\.c$,$1,;
     if ($source !~ m,\n \* ([\S ]+)\n \*/\n\n([\S ]+)\n$func\((.*?)\)\n\{,s) {
@@ -352,6 +362,8 @@ sub parse_source($) {
 	'errors'	=> \@errors,
 	'author'	=> $author,
 	'customrv'	=> $customrv,
+	'deprecated'	=> $deprecated,
+	'experimental'	=> $experimental,
     };
     if ($source =~ m/^ \* NODOC\s*$/m) {
 	$FUNCTIONS{$func}->{'nodoc'} = 1;
@@ -473,8 +485,24 @@ sub gendoc($) {
     $mdoc .= ".Ft \"$func->{'type'}\"
 .Fn $func->{'name'} $func->{'args'}
 .Sh DESCRIPTION
-$func->{'man'}
 ";
+    if (defined($func->{'deprecated'})) {
+	$mdoc .= ".Bf Em\n" .
+	    "This function is deprecated and may be removed " .
+	    "in a future release without further warning.\n";
+	if ($func->{'deprecated'}) {
+	    $mdoc .= "The\n.Fn $func->{'deprecated'}\nfunction " .
+		"may be used to achieve similar results.\n";
+	}
+	$mdoc .= ".Ef\n.Pp\n";
+    }
+    if ($func->{'experimental'}) {
+	$mdoc .= ".Bf Em\n" .
+	    "This function is experimental and may be modified or removed" .
+	    "in a future release without further warning.\n";
+	$mdoc .= ".Ef\n.Pp\n";
+    }
+    $mdoc .= "$func->{'man'}\n";
     my @errors = @{$func->{'errors'}};
     if ($func->{'customrv'}) {
 	# leave it