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

List:       kde-devel
Subject:    Re: KDE Documentation & deprecated API
From:       Andreas Simon <yuipx () gmx ! net>
Date:       2002-02-26 13:20:50
[Download RAW message or body]

On Tue, 2002-02-26 at 13:37, gordon.machel@t-online.de wrote:

> I'm currently browsing through the API docs as well, 
> as I'm preparing them for the use with doxygen. The 
> reason for the observed behaviour is that sometimes 
> the @deprecated command is followed by a '.' or a ',',
> thereby preventing the parser from recognizing the 
> command.

Yes, line 88 in kdoc/src/kdocParseDoc.pm is obviously wrong:

	elsif ( $text =~ /^\s*\@deprecated\s*/ ) {

I guess it should better be

	elsif ( $text =~ /^\s*\@deprecated[:punct:]?\s*/ ) {

(my perl is a little bit rusty) Does anyone want to commit?
Or should the ...

	# find ~/src/kdecvs/ -name "*.h" -exec \
	> grep deprecated[\\.\\;] {} \;|wc -l
	44

... 44 occurences of 'deprecated[.,]' be substituted with
'deprecated '?

> I vote for using @deprecated. Doxygen has such a command 
> already built in. It requires you to give additional text
> explaining why the method or class is deprecated, though.
> Kdoc, on the other hand, just inserts some predefined text,
> I think. Note that there is also @obsolete, which does a 
> similar thing.

Yes, there should always be text explaining why the method
or whatever is deprecated or at least what to use instead.
BTW I can't find @obsolete in the KDoc parser.

What is the plan with doxygen? Will it replace KDoc?

Cheers,
Andreas Simon

 
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<
[prev in list] [next in list] [prev in thread] [next in thread]