[wx-dev] Re: doxygen docs: @since vs. @wxsince

[Vaclav Slavik]

Hi,

Francesco Montorsi wrote:
> the change is small respect the original Doxygen command and allows
> us to do a thing which we can't do just with CSS,

(Actually, you can do that using CSS2.1 and its :before selector to; 
it's the visible only with CSS on, but then, it _is_ just styling 
thing.)

> Since:
>         2.9.0
>
> a bit ugly and "raw".

It may be, but it is still easily understood (I certainly never had 
any problems with understanding gtk-doc's "Since: 2.4"). And unlike 
@wxsince, it's easier to write free-form description when needed, 
without having to think about (and _check_) what text does @wxsince 
prepend and tweaking the text to not sound bad with @wxsince's 
prefix. For example:

    @since wxScrolled template exists since version 2.9.0. In older
           versions, only ::wxScrolledWindow (equivalent of
           wxScrolled<wxPanel>) was available.

> Also I don't think its syntax needs to be remembered; only its
> usage does

Yes, but that's exactly the problem. I -- and others -- use Doxygen 
for documenting other things that wx and @since is standard command 
that I can use everywhere, without thinking about it -- it's like 
@see, @param, @remarks and so on. Also, I get syntax highlighting for 
it and so I immediately spot any typo when I make it.

IOW, it does make real difference, so I went ahead and changed it. As 
you say, it's a simple substitution, so at worst we'll change it 
back.

Regards,
Vaclav


-- 
PGP key: 0x465264C9, available from http://pgp.mit.edu/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://lists.wxwidgets.org/pipermail/wx-dev/attachments/20080421/4665dabf/attachment.pgp