From 2fc3fbb41dbd81a92dfe27a22b31f36b10ea37ca Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Mon, 23 May 2016 21:02:39 +0000 Subject: 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. --- static/includes/database.inc.php | 4 ++- static/includes/settings.inc.php | 71 ++++++++++++++++++++++++++++++++++------ 2 files changed, 64 insertions(+), 11 deletions(-) (limited to 'static/includes') 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 @@ + * Prepares a PDO connection between Pomf and a database server. + * + * @copyright Copyright (c) 2013 Peter Lejeck * * 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 @@ - * Copyright (c) 2015 cenci0 - * Copyright (c) 2015 the Pantsu.cat developers + * User configurable settings for Pomf. + * + * @copyright Copyright (c) 2013, 2014 Peter Lejeck + * @copyright Copyright (c) 2015 cenci0 + * @copyright Copyright (c) 2015 the Pantsu.cat developers + * * * 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', -- cgit v1.2.3