[Geany-devel] build API - Re: SF.net SVN: geany:[4367] trunk

[Nick Treleaven]

On Fri, 30 Oct 2009 09:03:37 +1100
Lex Trotman <elextr at gmail.com> wrote:

> >> I was actually thinking about a plugin that tried to save and restore
> >> structure contents so it could restore values after running or save
> >> them to file for restore next time.  The struct might be allocated
> >> prior to the plugin being loaded.
> >
> > I think plugins shouldn't try to do that. If it was necessary, we could
> > add functions to the API for any structures that need to be synced
> > from/to disk.
> 
> Thats what I was saying, this should be on the list separate to allocate :-)
...
> >> > What do you mean by structure invariants?
> >>
> >> Required relationships between members of structures, for example if
> >> GeanyBuildCommand has a non-null label it might reasonably require a
> >> non-null command and working directory to save checking all the time.
> >> (Note actually I think I test all of them all the time but its an
> >> example :-)
> >>
> >> The API functions I provided all checked parameters then called
> >> internal versions that didn't.
> >
> > Basically plugins probably shouldn't really set any of the exposed
> > struct fields, only read them. Maybe we should mark them as const but
> > I'm not sure if this would cause issues.
> 
> Yes if all the API functions returned const pointers.  That doesn't
> stop some conniving plugin writer from casting them non-const but that
> is deliberate rather than accidental misuse so bugs are firmly the
> plugin writers problem.

The problem with that is that you might want to call an API function
that changed the struct, but you'd have to pass it a const struct or
cast the const away.

> > Anyway, we could improve the API docs (doxygen) to warn about these
> > things. (The HACKING file is for working on Geany's core).
> 
> Or maybe both so there's a chance it will be seen, remember we're
> talking about programmers reading the manual :-)

Plugin writers have to read the API docs anyway, they don't need to
read HACKING. I don't want to duplicate things really.

Regards,
Nick