Extend and improve PHP code comments (PHPDoc)

Add file summaries, @copyright tags and other comments. Covers majority
of the PHP code base now. I have avoided being too verbose and omitted
some potential tags.

Most visibly to the user, this comments every user configurable setting
and clarifies what some of the options do.

POMF_DB_USER and POMF_DB_PASS are not rendered perfectly in
phpDocumentor version 2.8.5. This is a sacrifice I made in attempt for
not being too verbose and obvious.

Response class gets a @todo for being a god object.

2 files changed, 64 insertions, 11 deletions

diff --git a/static/includes/database.inc.php b/static/includes/database.inc.php
index ff04561..7a1d4f9 100644
--- a/static/includes/database.inc.php
+++ b/static/includes/database.inc.php
@@ -1,7 +1,9 @@
 <?php
 
 /**
- * Copyright (c) 2013 Peter Lejeck <peter.lejeck@gmail.com>
+ * Prepares a PDO connection between Pomf and a database server.
+ *
+ * @copyright Copyright (c) 2013 Peter Lejeck <peter.lejeck@gmail.com>
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
diff --git a/static/includes/settings.inc.php b/static/includes/settings.inc.php
index 6072249..ce6fa5e 100644
--- a/static/includes/settings.inc.php
+++ b/static/includes/settings.inc.php
@@ -1,9 +1,12 @@
 <?php
 
 /**
- * Copyright (c) 2013, 2014 Peter Lejeck <peter.lejeck@gmail.com>
- * Copyright (c) 2015 cenci0 <alchimist94@gmail.com>
- * Copyright (c) 2015 the Pantsu.cat developers <hostmaster@pantsu.cat>
+ * User configurable settings for Pomf.
+ *
+ * @copyright Copyright (c) 2013, 2014 Peter Lejeck <peter.lejeck@gmail.com>
+ * @copyright Copyright (c) 2015 cenci0 <alchimist94@gmail.com>
+ * @copyright Copyright (c) 2015 the Pantsu.cat developers
+ * <hostmaster@pantsu.cat>
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -24,22 +27,70 @@
  * SOFTWARE.
  */
 
-// PDO socket
-// mysql.sock path can be different from /tmp/mysql.sock, see /etc/my.cnf
+/**
+ * PDO connection socket
+ *
+ * Database connection to use for communication. Currently, MySQL is the only
+ * DSN prefix supported.
+ *
+ * @see http://php.net/manual/en/ref.pdo-mysql.connection.php PHP manual for
+ * PDO_MYSQL DSN.
+ * @param string POMF_DB_CONN DSN:host|unix_socket=hostname|path;dbname=database
+ */
 define('POMF_DB_CONN', 'mysql:unix_socket=/tmp/mysql.sock;dbname=pomf');
-// MySQL user and password
+
+/**
+ * PDO database login credentials
+ */
+
+/** @param string POMF_DB_NAME Database username */
 define('POMF_DB_USER', 'pomf');
+/** @param string POMF_DB_PASS Database password */
 define('POMF_DB_PASS', '***');
 
-// Root location of files
+/**
+ * File system location where to store uploaded files
+ *
+ * @param string Path to directory with trailing delimiter
+ */
 define('POMF_FILES_ROOT', '/mnt/pantsu/http/files/');
-// Maximum number of iterations while generating a new filename
+
+/**
+ * Maximum number of iterations while generating a new filename
+ *
+ * Pomf uses an algorithm to generate random filenames. Sometimes a file may
+ * exist under a randomly generated filename, so we count tries and keep trying.
+ * If this value is exceeded, we give up trying to generate a new filename.
+ *
+ * @param int POMF_FILES_RETRIES Number of attempts to retry
+ */
 define('POMF_FILES_RETRIES', 15);
-// Number of random characters to use in a new filename
+
+/**
+ * The length of generated filename (without file extension)
+ *
+ * @param int POMF_FILES_LENGTH Number of random alphabetical ASCII characters
+ * to use
+ */
 define('POMF_FILES_LENGTH', 6);
-// URL to prepend to output (include trailing slash)
+
+/**
+ * URI to prepend to links for uploaded files
+ *
+ * @param string POMF_URL URI with trailing delimiter
+ */
 define('POMF_URL', 'https://i.pantsu.cat/');
 
+/**
+ * Double dot file extensions
+ *
+ * Pomf keeps the last file extension for the uploaded file. In other words, an
+ * uploaded file with `.tar.gz` extension will be given a random filename which
+ * ends in `.gz` unless configured here to ignore discards for `.tar.gz`.
+ *
+ * @param string[] $doubledots Array of double dot file extensions strings
+ * without the first prefixing dot
+ */
 $doubledots = array_map('strrev', array(
     'tar.gz',
     'tar.bz',