[GSoC] GObjectification Summary

[Mark Doliner]

On Sat, Dec 7, 2013 at 5:57 PM, Ankit Vani <a at nevitus.org> wrote:
> On Sun, Dec 8, 2013 at 12:51 AM, Mark Doliner <mark at kingant.net> wrote:

> This branch also changes some of the prefs, which makes the new prefs not
> compatible with the current branch. If needed, we will need to write code to
> convert old prefs to new.

I do think we should write code to convert old prefs to new. It's nice
for users when things work as expected. And I think just a few
frustrating experiences (e.g. "I upgraded Pidgin and my accounts
didn't automatically sign in!") erode good will quickly.

>> Regarding gtk-doc vs. doxygen, I'm in favor of switching. It seems
>> like gtk-doc has become the de facto standard for glib, gtk, gnome
>> libraries. And as a developer I prefer the formatting/appearance of
>> gtk-doc rather than doxygen. Personally I'd like to see us switch to
>> gtk-doc regardless of your .plugins branch. Anyone object to this?
>>
>> Regarding the actual changes, it looks like you've done some work in
>> your .plugins branch, but you're saying that every doc-style comment
>> on all our functions and structs will need to change to use gtk-doc
>> style? That change seems pretty straightforward... maybe we should
>> make that change directly in the default branch and go ahead and check
>> it in now? That way the .plugins branch contains only changes related
>> to the plugin API.
>
> I am in favour of this.

Well then you're more than welcome to make this change :-) You could
do it in default or in a separate branch. Either way sounds fine to
me.

> Changing the documentation format in the code is the challenge. Any ideas on how
> this can be automated? I had started working on a converter but its not finished
> yet, and actually probably needs better planning..

I'm not aware of any tools to automate this, but I also haven't
searched. The format of things like @param and @return is fairly
similar, isn't it? Seems like you could write a python script that
looks at files line by line, looks for " * @param" and reformats the
line appropriately, and maybe that would take care of a large chunk of
the changes and the rest could be done by hand.