Re: fun project!

[Tim Janik <timj gtk org>]

On 26 Apr 2000, Havoc Pennington wrote:

> 
> Hi,
> 
> The GTK+ sources need to be marked up with magic comments describing
> certain parameters and return values, for the benefit of language
> bindings. Most commonly:
> 
>  - whether returned values do/don't need to be freed
>  - whether returned values or parameters can be NULL
> 
> Magic comments should only be added for non-standard
> behavior. Standard behavior is:
>  - arguments can't be NULL
>  - return values can't be NULL
>  - returned strings must be freed
>  - returned GtkObject should not be unreferenced

i think we should keep magic commenting to the minimum possible,
if at all, so we better make sure the default choosen apply to the
commmon case. for strings specifically this means:
- returned strings usually do not need to be freed
- strings can most often be passed as NULL, (tooltips, label text...)
- returned strigs may be NULL

> Some proposed magic comments after talking to Owen briefly:
> 
>  - /*< nofree >*/      a return value or arg not to free
>  - /*< mustfree >*/    one you have to free
>  - /*< nullok >*/      something that can be NULL
>  - /*< nonull >*/      something that can't
> 
> Combine options with comma:
>  /*< nofree, nullok >*/

the whole idea of putting magic comments into gtk for the parameters
came up before, and last time it was put down because the knowledge
of whether a certain arg needs to be freed etc... should go into
the .defs file. i'd like to know where exactly we stand with that
before cluttering gtk headers.

> 
> Havoc
>  

---
ciaoTJ