Added Gtk-Doc in 3.0

[Ankit Vani]

Hi

I have just merged gtk-doc conversion into main for 3.0. To generate
documentation, you have to pass --enable-gtk-doc to configure, and docs
will be generated after compiling pidgin.

For those unfamiliar, if you are documenting new code, I suggest referring
to [1] to understand how gtk-doc comments are like. It would also be
helpful if you could provide annotations and/or help annotate existing
documentation, which will be very useful during introspection (currently
WIP in soc.2013.gobjectification.plugins in my SOC 2013 repo). For
annotations, please refer [2].

When adding new header files to the public API, please add an entry to
doc/reference/{libpurple|pidgin|finch}/libpurple-docs.xml, as to where you
want it on the index page. To ignore directories or header files from
documentation, add an entry to IGNORE_HFILES in
doc/reference/{libpurple|pidgin|finch}/Makefile.am.

When generating documentation, you will see a lot of warnings regarding
missing documentations for parameters, members etc. For now, I have only
converted existing documentation. It would be nice to reduce these
warnings by documenting more stuff. Also, currently I have only converted
the comments for the directories that are going to be scanned for docs
(libpurple, libpurple/ciphers, libpurple/media, finch, finch/libgnt,
pidgin). Documentation will not be generated for subdirectories I did not
list -- however warnings are generated for directories such as protocols,
plugins etc. during scanning, which really shouldn't happen as they are
set to be ignored from documenting. Cross-referencing warnings will depend
on the docs you have installed (for example if you don't have GLib docs,
you'll get warnings for missing references to glib functions from
generated docs).

Also, gtk-doc requires things to be libraries for it to introspect them
for GObjects etc. So finch and pidgin are first built as libpidgin and
libfinch (not installed), and then produced as executables. I checked a to
see if there was any other way and how other application projects handled
this, and it seems they all have done this.

Please review and add, remove, modify and rearrange the documentation as
you see fit.

Ankit Vani

[1] - https://developer.gnome.org/gtk-doc-manual/1.17/documenting.html.en
[2] - https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations/Old