# Process formatting within sections.
for my $parameter (@parameters) {
- process_formatting(\$parameter->{description});
+ process_formatting(\$parameter->{description}, $file_path, $.);
+ }
+ process_formatting(\$returns, $file_path, $.);
+ process_formatting(\$body, $file_path, $.);
+ if (defined($deprecated)) {
+ process_formatting(\$deprecated, $file_path, $.);
}
- process_formatting(\$returns);
- process_formatting(\$body);
$body =~ s/\n/ /g;
if (exists($docs->{body}->{$name})) {
$_ = '<p>' if /^\s*$/;
if ($section == $PARAMETER_SECTION) {
- if (/\s*(\w+):(.*)/) {
+ if (/\s*\\param +(\w+)(.*)/) {
+ # print "$file_path:$.: warning: Got parameter $1\n";
+ push @parameters, { name => $1, description => $2 };
+ } elsif (/\s*\\deprecated(.*)/) {
+ # print "$file_path:$.: warning: Got deprecated annotation\n";
+ $deprecated = $1;
+ } elsif (/\s*(\w+):(.*)/) {
if ($1 eq 'deprecated') {
+ warn "$file_path:$.: Old-style monodoc notation 'deprecated:' used\n"
+ if $WARNINGS;
$deprecated = $2;
} else {
+ warn "$file_path:$.: Old-style monodoc notation 'param:' used\n"
+ if $WARNINGS;
push @parameters, { name => $1, description => $2 };
}
} else {
- $body = "\t$_\n";
+ # $body = "\t$_\n";
$section = $BODY_SECTION;
+ redo;
}
} elsif ($section == $BODY_SECTION) {
- if (/Returns?:/) {
- s/Returns?://;
+ if (s/(Returns?:\s*|\\returns?\s*)//) {
$returns = "\t$_\n";
$section = $RETURN_SECTION;
} else {
# Substitute formatting within documentation text.
#
sub process_formatting {
- my ($content) = @_;
+ my ($content, $file_path, $current_line) = @_;
$_ = $$content;
# Constants
s{FALSE}{<code>FALSE</code>}g;
# Parameters
- s{@(\w+)}{<i>$1</i>}g;
+ warn "$file_path:$current_line: Old-style monodoc notation '\@param' used\n"
+ if s{@(\w+)}{<i>$1</i>}g && $WARNINGS;
+ s{\\p +(\w+)}{<i>$1</i>}g;
# Code
- s{#(\w+)}{<code>$1</code>}g;
- s{\`([:.\w\*]+)\`}{<code>$1</code>}g;
+ warn "$file_path:$current_line: Old-style monodoc notation '#code' used\n"
+ if s{#(\w+)}{<code>$1</code>}g && $WARNINGS;
+ warn "$file_path:$current_line: Old-style monodoc notation '`code`' used\n"
+ if s{\`((?!api:)[:.\w\*]+)\`}{<code>$1</code>}g && $WARNINGS;
+ s{\\c +(\S+(?<![.,:;]))}{<code>$1</code>}g;
$$content = $_;
}