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/settings.inc.php | 71 ++++++++++++++++++++++++++++++++++------ 1 file changed, 61 insertions(+), 10 deletions(-) (limited to 'static/includes/settings.inc.php') 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 From 118e7a7e53f32cc4ed76ec164de4835619d319d4 Mon Sep 17 00:00:00 2001 From: Juuso Lapinlampi Date: Mon, 23 May 2016 21:21:14 +0000 Subject: Add Pantsu.cat copyright year 2016 for recent change Claiming copyright for parts of UploadedFile.class.php and settings.inc.php as per previous change, which introduced PHPDoc comments. The other files where edits were made in previous commits are non-substantial and thus most likely not under copyright. --- static/includes/settings.inc.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'static/includes/settings.inc.php') diff --git a/static/includes/settings.inc.php b/static/includes/settings.inc.php index ce6fa5e..872fde0 100644 --- a/static/includes/settings.inc.php +++ b/static/includes/settings.inc.php @@ -5,7 +5,7 @@ * * @copyright Copyright (c) 2013, 2014 Peter Lejeck * @copyright Copyright (c) 2015 cenci0 - * @copyright Copyright (c) 2015 the Pantsu.cat developers + * @copyright Copyright (c) 2015, 2016 the Pantsu.cat developers * * * Permission is hereby granted, free of charge, to any person obtaining a copy -- cgit v1.2.3