[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-kdoc
Subject:    Half-solution (patch): Exception matters (and non-described params)
From:       Marcin Kasperski <Marcin.Kasperski () softax ! com ! pl>
Date:       1999-04-13 12:29:49
[Download RAW message or body]

> 2) I found (with pleasure) that I can insert multiple @exception tags
> and the exception are concatenated. But unfortunately I still can not
> insert any exception description: if I say
> 
> @exception A dangerous error A happened
> @exception B less dangerous thing
> 
> I got from kdoc:
> 
> Exceptions: A, dangerous, error, A, happened, B, less, dangerous, thing
> 
> That's not what I'd like to...
> 

... so I patched kdoc a bit. The patch below causes kdoc to treat
@exception's just like @param's - create small table with all possible
exceptions. This patch also corrects kdoc bug which caused @params's
(and after patch @exceptions) without description to be skipped.

1) Changes in kdocParseDoc.pm

I changed exception regexp in newDocComment to behave like param regexp:
To gather @exception's just like @param's I replaced

		elsif( $text =~ /^\s*\@(?:throws|exception|raises)\s*/ ) {
			docListProp( "Throws" );
                }
with
		elsif( $text =~ /^\s*\@(?:throws|exception|raises)\s+(\w+)\s*/ ) {
                        textProp( "Throws" );
                        $extraprops{ "Name" } = $1;
                }

To remove bug which caused @exceptions and @params without description
not to be printed I changed flushProp subroutine: I replaced
	return if $buffer eq "";
with
        return if ($buffer eq "" && ! scalar(%extraprops));


2) Changes in kdocHTMLutil.pm

To print exceptions just like params - in dedicated table - I modified
printDoc function. I replaced:

	# Exceptions
	$text = $docNode->{Throws};

	if ( defined $text ) {

		my $comma = "<p><b>Throws</b>: ";

		foreach $tosee ( @$text ) {
			print CLASS $comma, esc( $tosee );
			$comma = ", ";
		}
		print CLASS "</p>\n";
	}

with

	# Exceptions
        my @exception_list = ();
        kdocAstUtil::findNodes( \@exception_list, $docNode->{Text},
                                "NodeType", "Throws" );
        if( $#exception_list >= 0 ) {
		my $pnode;
		print CLASS "<p><b>Throws</b>:",
			"<TABLE BORDER=\"0\" CELLPADDING=\"5\">\n";
		
		foreach $pnode ( @exception_list ) {
			print CLASS "<TR><TD align=\"left\" valign=\"top\"><i>",
				esc($pnode->{Name}),
				"</i></TD><TD align=\"left\" valign=\"top\">",
				deref($pnode->{astNodeName}, $rootnode ),
				"</TD></TR>\n";
		}
		print CLASS "</TABLE></P>\n";
        }

and now I'm happier.

-- Marcin Kasperski     Marcin.Kasperski<at>softax.com.pl
--                      marckasp<at>friko6.onet.pl
-- Moje poglądy są moimi poglądami, nikogo poza mną nie reprezentują.
-- (My opinions are just my opinions.)

[prev in list] [next in list] [prev in thread] [next in thread]