diff options
author | Stefan Sauer <ensonic@users.sf.net> | 2014-07-10 07:26:32 +0200 |
---|---|---|
committer | Stefan Sauer <ensonic@users.sf.net> | 2014-07-10 07:29:19 +0200 |
commit | 5be5b88761bf4284c3a93f046247dd44ec85d874 (patch) | |
tree | d762247e218c65672f83c755c361faeb9b7640a2 | |
parent | 776edf4d952107cf5b1aa3de5f557eda2e3a45b6 (diff) | |
download | gtk-doc-5be5b88761bf4284c3a93f046247dd44ec85d874.tar.gz |
mkdb: drop legacy 'return' description handling
We don't recognize sentences starting with 'Returns' as return docs anymore.
This was ambigous and we printed a warning for this since years.
FIxes #678094
-rwxr-xr-x | gtkdoc-mkdb.in | 40 |
1 files changed, 9 insertions, 31 deletions
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in index e53f136..de0d35d 100755 --- a/gtkdoc-mkdb.in +++ b/gtkdoc-mkdb.in @@ -3903,10 +3903,9 @@ sub ScanSourceFile { my $in_comment_block = 0; my $symbol; my $in_part = ""; - my ($description, $return_desc, $return_start, $return_style); + my ($description, $return_desc); my ($since_desc, $stability_desc, $deprecated_desc); my $current_param; - my $ignore_broken_returns; my @params; while (<SRCFILE>) { # Look for the start of a comment block. @@ -3923,12 +3922,10 @@ sub ScanSourceFile { $in_part = ""; $description = ""; $return_desc = ""; - $return_style = ""; $since_desc = ""; $deprecated_desc = ""; $stability_desc = ""; $current_param = -1; - $ignore_broken_returns = 0; @params = (); } next; @@ -3942,11 +3939,10 @@ sub ScanSourceFile { } else { # Add the return value description onto the end of the params. if ($return_desc) { + # TODO(ensonic): check for duplicated Return docs + # &LogWarning ($file, $., "Multiple Returns for $symbol."); push (@params, "Returns"); push (@params, $return_desc); - if ($return_style eq 'broken') { - &LogWarning ($file, $., "Free-form return value description in $symbol. Use `Returns:' to avoid ambiguities."); - } } # Convert special SGML characters $description = &ConvertSGMLChars ($symbol, $description); @@ -3967,7 +3963,6 @@ sub ScanSourceFile { } @TRACE@("SECTION DOCS found in source for : '$real_symbol'\n"); - $ignore_broken_returns = 1; for ($k = 0; $k <= $#params; $k += $PARAM_FIELD_COUNT) { @TRACE@(" '".$params[$k]."'\n"); $params[$k] = "\L$params[$k]"; @@ -4056,7 +4051,6 @@ sub ScanSourceFile { if (m%^\s*(SECTION:\s*\S+)%) { $symbol = $1; @TRACE@("SECTION DOCS found in source for : '$symbol'\n"); - $ignore_broken_returns = 1; } elsif (m%^\s*([\w:-]*\w)\s*:?\s*(\([-a-z0-9_ ]+\)\s*)*$%) { $symbol = $1; @TRACE@("SYMBOL DOCS found in source for : '$symbol'\n"); @@ -4069,25 +4063,13 @@ sub ScanSourceFile { s%^\s*Description:%%; } - if (m/^\s*(returns:|return\s+value:)/i) { - if ($return_style eq 'broken') { - $description .= $return_start . $return_desc; - } - $return_start = $1; - if ($return_style eq 'sane') { - &LogWarning ($file, $., "Multiple Returns for $symbol."); + if (m%^\s*(returns|return\s+value):%i) { + # we're in param section and have not seen the blank line + if($in_part ne "") { + $return_desc = $'; + $in_part = "return"; + next; } - $return_style = 'sane'; - $ignore_broken_returns = 1; - $return_desc = $'; - $in_part = "return"; - next; - } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) { - $return_start = $1; - $return_style = 'broken'; - $return_desc = $'; - $in_part = "return"; - next; } elsif (m%^\s*since:%i) { # we're in param section and have not seen the blank line if($in_part ne "") { @@ -4141,10 +4123,6 @@ sub ScanSourceFile { if ($param_name =~ m/^\.\.\.$/) { $param_name = "..."; } - if ("\L$param_name" eq "returns") { - $return_style = 'sane'; - $ignore_broken_returns = 1; - } @TRACE@("Found param for symbol $symbol : '$param_name'= '$_'"); push (@params, $param_name); |