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
This commit is contained in:
Dag-Erling Smørgrav 2012-04-14 14:52:40 +00:00
parent d4b138c0e3
commit cf9114a400
4 changed files with 43 additions and 6 deletions

View File

@ -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.

View File

@ -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.
*

View File

@ -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
*

View File

@ -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