docs: Clean up file headers

Krinkle · Krinkle · commit e6f48448a782 · 2020-04-18T18:54:33.000+01:00
* Move license header to very top of the file as other Wikimedia
  projects do. This makes the top consistently ignorable,
  which is not the case if e.g. namespace and imports are above it.

* Remove file-level docs for files that only contain one class.
  These docs are basically inaccessible in the Doxygen output,
  as they don't appear on the class page. Merge them into the
  class-level docs instead.

* Remove `@file` for files that only contain a single class,
  they are not useful in the Doxgen navigation as they are just
  empty pages with a link to a single class (and tend to add noise
  to the in-doc search results).

* Add `@copyright` above the license so that the header doesn't
  get indexed as the description of namespaces etc. When
  a given intermediary namespace like "Cdb\Writer" doesn't have
  its own doc block, then whichever file first declares it
  will have the comment above it used as its description, which
  added lots of "This program is free software …" to the doc
  index.

Change-Id: I9f72da338522f29fd2aada054ae4e41ec8af369b
diff --git a/src/Exception.php b/src/Exception.php
@@ -1,8 +1,6 @@
 <?php
-
-namespace Cdb;
-
 /**
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -17,10 +15,10 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb;
+
 /**
  * Exception for Cdb errors.
  */
diff --git a/src/Reader.php b/src/Reader.php
@@ -1,10 +1,6 @@
 <?php
-
-namespace Cdb;
-
 /**
- * Native CDB file reader and writer.
- *
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -19,14 +15,15 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb;
+
 /**
- * Read from a CDB file.
- * Native and pure PHP implementations are provided.
- * http://cr.yp.to/cdb.html
+ * Read data from a CDB file.
+ * Native C and pure PHP implementations are provided.
+ *
+ * @see http://cr.yp.to/cdb.html
  */
 abstract class Reader {
 	/**
diff --git a/src/Reader/DBA.php b/src/Reader/DBA.php
@@ -1,13 +1,6 @@
 <?php
-
-namespace Cdb\Reader;
-
-use Cdb\Exception;
-use Cdb\Reader;
-
 /**
- * DBA-based CDB reader/writer
- *
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -22,12 +15,15 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb\Reader;
+
+use Cdb\Exception;
+use Cdb\Reader;
+
 /**
- * Reader class which uses the DBA extension
+ * Reader class which uses the DBA extension (php-dba)
  */
 class DBA extends Reader {
 	public function __construct( $fileName ) {
diff --git a/src/Reader/Hash.php b/src/Reader/Hash.php
@@ -1,13 +1,6 @@
 <?php
-
-namespace Cdb\Reader;
-
-use Cdb\Reader;
-
 /**
- * Hash implements the CdbReader interface based on an associative
- * PHP array (a.k.a "hash").
- *
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -22,10 +15,12 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb\Reader;
+
+use Cdb\Reader;
+
 /**
  * Hash implements the CdbReader interface based on an associative
  * PHP array (a.k.a "hash").
diff --git a/src/Reader/PHP.php b/src/Reader/PHP.php
@@ -1,15 +1,6 @@
 <?php
-
-namespace Cdb\Reader;
-
-use Cdb\Exception;
-use Cdb\Reader;
-use Cdb\Util;
-
 /**
- * This is a port of D.J. Bernstein's CDB to PHP. It's based on the copy that
- * appears in PHP 5.3.
- *
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -24,12 +15,19 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb\Reader;
+
+use Cdb\Exception;
+use Cdb\Reader;
+use Cdb\Util;
+
 /**
  * CDB reader class
+ *
+ * This is a port of D.J. Bernstein's CDB to PHP. It's based on the copy that
+ * appears in PHP 5.3.
  */
 class PHP extends Reader {
 
diff --git a/src/Util.php b/src/Util.php
@@ -1,14 +1,6 @@
 <?php
-
-namespace Cdb;
-
 /**
- * This is a port of D.J. Bernstein's CDB to PHP. It's based on the copy that
- * appears in PHP 5.3. Changes are:
- *    * Error returns replaced with exceptions
- *    * Exception thrown if sizes or offsets are between 2GB and 4GB
- *    * Some variables renamed
- *
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -23,12 +15,15 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb;
+
 /**
  * Common functions for readers and writers
+ *
+ * This is a port of D.J. Bernstein's CDB to PHP. It's based on the copy that
+ * appears in PHP 5.3.
  */
 class Util {
 	/**
diff --git a/src/Writer.php b/src/Writer.php
@@ -1,10 +1,6 @@
 <?php
-
-namespace Cdb;
-
 /**
- * Native CDB file reader and writer.
- *
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -19,14 +15,15 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb;
+
 /**
  * Write to a CDB file.
- * Native and pure PHP implementations are provided.
- * http://cr.yp.to/cdb.html
+ * Native C and pure PHP implementations are provided.
+ *
+ * @see http://cr.yp.to/cdb.html
  */
 abstract class Writer {
 	/**
diff --git a/src/Writer/DBA.php b/src/Writer/DBA.php
@@ -1,13 +1,6 @@
 <?php
-
-namespace Cdb\Writer;
-
-use Cdb\Exception;
-use Cdb\Writer;
-
 /**
- * DBA-based CDB reader/writer
- *
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -22,12 +15,15 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb\Writer;
+
+use Cdb\Exception;
+use Cdb\Writer;
+
 /**
- * Writer class which uses the DBA extension
+ * Writer class which uses the DBA extension (php-dba)
  */
 class DBA extends Writer {
 	/**
diff --git a/src/Writer/PHP.php b/src/Writer/PHP.php
@@ -1,18 +1,6 @@
 <?php
-
-namespace Cdb\Writer;
-
-use Cdb\Exception;
-use Cdb\Util;
-use Cdb\Writer;
-
 /**
- * This is a port of D.J. Bernstein's CDB to PHP. It's based on the copy that
- * appears in PHP 5.3. Changes are:
- *    * Error returns replaced with exceptions
- *    * Exception thrown if sizes or offsets are between 2GB and 4GB
- *    * Some variables renamed
- *
+ * @copyright
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -27,12 +15,19 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
  */
 
+namespace Cdb\Writer;
+
+use Cdb\Exception;
+use Cdb\Util;
+use Cdb\Writer;
+
 /**
  * CDB writer class
+ *
+ * This is a port of D.J. Bernstein's CDB to PHP. It's based on the copy that
+ * appears in PHP 5.3.
  */
 class PHP extends Writer {
 	protected $hplist;
diff --git a/tests/CdbTest.php b/tests/CdbTest.php
@@ -1,13 +1,9 @@
 <?php
-
 namespace Cdb\Test;
 
 use Cdb\Reader;
 use Cdb\Writer;
 
-/**
- * Test the CDB reader/writer
- */
 class CdbTest extends \PHPUnit\Framework\TestCase {
 	/** @var string */
 	private $phpCdbFile, $dbaCdbFile;
