[Librefm-discuss] Installation and code documentation, exception catching, etc.

[P. J. McDermott]

Hi all,

Hopefully this message makes it to the list; my last one[1] about GSoC
didn't.

As I installed GNU FM on my Debian GNU/Linux desktop, I wrote up an
installation guide[2], noting some Debian peculiarities that may not be
obvious to many people. Should this go on the tracker wiki? It seems I
can't start new pages there.

Also in the interest of documentation, I installed phpDocumentor,
learned how to use it on the command line, and ran it on Nixtape and
GNUkebox (separately, since there are no @package tags to distinguish
them in the documentation). Ideally this should be hosted somewhere
under the libre.fm domain and probably automated (I can provide a
phpDocumentor converter template for GNU FM and some commands to
generate HTML documentation), but for now I can host it myself.[3][4] I
noticed some minor issues in some DocBlocks (like starting a variable
description with "A"/"An" where phpDocumentor expects a data type), and
I excluded ARC2 and the Janrain OpenID library from the documentation
(they're documented elsewhere and add a lot of noise here). But
hopefully this documentation should help newcomers like myself to more
quickly understand the codebase's design.

I saw an exception-related issue (#246) on the tracker and another one
related to ADOdb on the mailing list[5], so I thought I'd throw together
a grep(1)-like PHP script (findthrows[6]) to find functions/methods that
throw exceptions. Then I/we could use this to find function calls that
should be encapsulated in try...catch blocks, hopefully ultimately
avoiding all such problems. A script to read the output of findthrows
and search for these function calls automatically would be nice, but I
can't think of any good way to do it. To properly bind class names to
object variable names (the pains of a dynamically-typed language,
sadly), it would need to parse and execute the PHP code. Alternatively,
we could at least just use tools like grep(1) to find the function
calls. But even with findthrows this will be rather tedious in ADOdb,
since all exceptions are thrown through one function:
  $ ./findthrows -ifnR /usr/share/php/adodb
  /usr/share/php/adodb/adodb-exceptions.inc.php:78:adodb_throw():$errfn

Catching the exception seen in #246 wouldn't solve the bug per se (why
is the exception being thrown in the first place? is there a space at
the end of the artist name or something?), but it's a quick fix (a good
candidate for my first patch I suppose) and it would at least restore
access to the user's profile page once it reaches Libre.fm. When I have
more time, I'd like to set up a new installation of GNU FM with the
Libre.fm data and try to reproduce the error. For now though, I've
registered[7] on Gitorious (something I've been meaning to do for some
time now), cloned gnu-fm, and started learning[8] Git; so I'll probably
patch this exception issue tomorrow.

P. J. McDermott

[1] http://pehjota.pzt.me/nvhi
[2] http://fm.pehjota.com/docs/install.html
[3] http://fm.pehjota.com/docs/gnukebox/
[4] http://fm.pehjota.com/docs/nixtape/
[5]
http://lists.nongnu.org/archive/html/librefm-discuss/2010-06/msg00001.html
[6] http://fm.pehjota.com/findthrows/
[7] https://gitorious.org/~pehjota
[8] https://gitorious.org/librcio/librcio