Re: Version information

[Owen Taylor <otaylor redhat com>]

Damon Chaplin <damon kendo fsnet co uk> writes:

> On Sun, 2002-10-20 at 20:27, Matthias Clasen wrote:
> > 
> > Hi all, 
> > 
> > I'd like to see information about when an interface was added. My first
> > attempt was to add this information to the $MODULE-sections.txt file,
> > like the following example: 
> > 
> > <TITLE>Module Interface</TITLE>
> > <FILE>module_interface</FILE>
> > gdk_pixbuf_set_option
> > gdk_pixbuf_get_formats            2.1.0
> > gdk_pixbuf_format_get_name        2.1.0
> > gdk_pixbuf_format_get_description 2.1.0
> > gdk_pixbuf_format_get_mime_types  2.1.0
> > gdk_pixbuf_format_get_extensions  2.1.0
> > gdk_pixbuf_format_is_writable     2.1.0
> > GdkPixbufFormat                   2.1.0
> > GdkPixbufFormatFlags              2.1.0
> > GdkPixbufModulePattern            2.1.0
> > GdkPixbufModuleFillVtableFunc     
> > GdkPixbufModuleFillInfoFunc       2.1.0
> > GdkPixbufModuleSizeFunc           2.1.0
> > GdkPixbufModulePreparedFunc
> > GdkPixbufModuleUpdatedFunc
> > GdkPixbufModule
> > 
> > With the patch attached to #93591, gtk-doc will use this information to
> > emit "Since: 2.1.0" for the corresponding symbols. (Without the patch
> > gtk-doc will happily ignore the version info, as I've just verified) 
> > 
> > Does this look like an OK addition ? Do you think we also need to
> > support version information in the doc comments (like the javadoc @since
> > tag) ?
> 
> Yes, I think that is useful.
> 
> I'd be more inclined to go for inline comments, since eventually I'd
> like to see nearly all docs inline (except for long descriptions).

One possible reason for putting version information in -sections.txt
files (or allowing doing so) is that it is simply easier to do that
way, especially when backfilling for a bunch of symbols.

On the other hand, perhaps that isn't a good reason long term.

Another thing that comes to mind is that in the -sections.txt
you could have some way of indicating that an entire file should
get the "Since: 2.1.0" designation and avoid a lot of duplication.

Regards,
                                        Owen