Re: Since and deprecated

[Owen Taylor <otaylor redhat com>]

Matthias Clasen <maclas gmx de> writes:

> Here is a patch which supports Since: and Deprecated: lines in inline
> doc comments like:
> 
> /**
>  * do_something:
>  * @arg1: first arg
>  * @arg2: second arg
>  *
>  * Does something sometimes.
>  *
>  * Return: something else
>  *
>  * Since: 3.4.5
>  *
>  * Deprecated: This is completely useless. Use something else.
>  **/
> 
> The Since: information is currently just tacked at the very end of the
> refsection2, as <para>Since 3.4.5</para>, the deprecation information is
> added after the autogenerated deprecation statement, but inside the
> warning tag. gtk-doc will warn if it finds inline deprecation
> information for symbols which are not guarded by a deprecation #define.
> 
> Note that the repetitive aspects of the patch really point to some
> necessary refactoring of the gtk-doc code.

Indeed. We probably should make some effort to refactor incrementally
as we go along, since the big plan of major rework has existed
as long as gtk-doc, and not gotten much of anywhere.

> Index: gtkdoc-mkdb.in
> ===================================================================
> RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
> retrieving revision 1.62
> diff -u -b -B -p -r1.62 gtkdoc-mkdb.in
> --- gtkdoc-mkdb.in	12 Nov 2002 10:21:27 -0000	1.62
> +++ gtkdoc-mkdb.in	15 Nov 2002 14:49:48 -0000
> @@ -96,7 +96,7 @@ if (lc($OUTPUT_FORMAT) eq "xml") {
>      $empty_element_end = "/>";
>  
>      if ($MAIN_SGML_FILE && -e $MAIN_SGML_FILE) {
> -	print "scanning $MAIN_SGML_FILE";
> +	print "scanning $MAIN_SGML_FILE\n";

Maybe should just be removed?

> @@ -629,13 +630,21 @@ sub OutputMacro {
>      }
>  
>      if ($Deprecated{$symbol}) {

if ($Deprecated{symbol}) is string that Perl counts as false - 
say "0" or "", then this will fail. You want

 if (exists $Deprecated{$symbol}}) { .. }

Here and elsewhere where Deprecated is checked, and same for
Since{}.

[ 
  There is very little difference between exists $a{$b} and 
  defined $a{$b} - the former is array specific, the latter
  is more generic. The former may be a tad faster since
  it doesn't need to retrieve the value 
]

> -        $desc .= "<warning>\n<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n</warning>\n";
> +	$desc .= "<warning>\n";
> +	$desc .= "<para>\n<literal>$symbol</literal> is deprecated and should not be used in newly-written code.\n</para>\n";
> +	if ($Deprecated{$symbol} ne 1) {

ne is textual inequality, so you want ne "1" here. But really,
I would suggest a scheme of:

 $Deprecated{$symbol} => undef     not deprecated
 $Deprecated{$symbol} => ""        no extra text
 $Deprecated{$symbol} => ..        extra text

So, use if ($Deprecated{$symbol ne ""}) {}

> @@ -1943,6 +2004,23 @@ EOF
>  
>  		$SourceSymbolDocs{$symbol} = $description;
>  		$SourceSymbolParams{$symbol} = [ @params ];
> +
> +		if ($since_desc) {
> +		    $since_desc = &ConvertSGMLChars ($since_desc);
> +		    $Since{$symbol} = $since_desc;
> +		}

Would it be simpler to leave out the intermediate assignment
to $since_desc here?

> @@ -1972,12 +2050,58 @@ EOF
>  		$description .= $return_start . $return_desc;
>  		$return_start = $1;
>  		$return_desc = $';
> +	    } elsif (m%^\s*since:%i) {
> +#		print "SINCE after return: $_";
> +		$since_desc = $';
> +		$in_since = 1;
> +		$in_return = 0;
> +	    } elsif (m%^\s*deprecated:%i) {
> +#		print "DEPRECATED after return: $_";
> +		$deprecated_desc = $';
> +		$in_deprecated = 1;
> +		$in_return = 0;

Probably should remove the commented out print's here and in
similar places below.

In general, looks fine to me.

Regards,
                                        Owen