profiler: Clean up file headers and @ingroup

* Remove redundant file description for files that only define
  a class where the class description suffices.
* Ensure the file has a license header and @file.

* Remove any @ingroup from the file comment block.
  These clutter the Doxygen pages with duplicate entries.
* Ensure the class block has an @ingroup set.

* Remove @since when @internal is set.
* Add any missing @since to public classes that were created
  recently enough to easily find out when:
  - ProfilerExcimer was introduced in 1.33 (6373e3d1d4).

Change-Id: I6b18289a15a3085857acd7c9004ec819f7914b29

includes/profiler/Profiler.php

@@ -1,7 +1,5 @@
 <?php
 /**
- * Base class for profiling.
- *
  * 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
@@ -18,15 +16,17 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Profiler
- * @defgroup Profiler Profiler
  */
 use Wikimedia\Rdbms\TransactionProfiler;
 use Wikimedia\ScopedCallback;
 
 /**
- * Profiler base class that defines the interface and some trivial
- * functionality
+ * @defgroup Profiler Profiler
+ */
+
+/**
+ * Profiler base class that defines the interface and some shared
+ * functionality.
  *
  * @ingroup Profiler
  */

includes/profiler/ProfilerExcimer.php

@@ -1,5 +1,27 @@
 <?php
+/**
+ * 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
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * 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
+ */
 
+/**
+ * @ingroup Profiler
+ * @since 1.33
+ */
 class ProfilerExcimer extends Profiler {
 	/** @var ExcimerProfiler */
 	private $cpuProf;

includes/profiler/ProfilerStub.php

@@ -1,7 +1,5 @@
 <?php
 /**
- * Stub profiling functions.
- *
  * 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
@@ -18,11 +16,10 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Profiler
  */
 
 /**
- * Stub profiler that does nothing
+ * Stub profiler that does nothing.
  *
  * @ingroup Profiler
  */

includes/profiler/SectionProfileCallback.php

@@ -16,15 +16,14 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Profiler
  */
 use Wikimedia\ScopedCallback;
 
 /**
  * Subclass ScopedCallback to avoid call_user_func_array(), which is slow.
  *
+ * @ingroup Profiler
  * @internal For use by SectionProfiler
- * @since 1.25
  */
 class SectionProfileCallback extends ScopedCallback {
 	/** @var SectionProfiler */

includes/profiler/SectionProfiler.php

@@ -1,7 +1,5 @@
 <?php
 /**
- * Arbitrary section name based PHP profiling.
- *
  * 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
@@ -18,14 +16,16 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Profiler
  */
 use Wikimedia\ScopedCallback;
 
 /**
- * Custom PHP profiler for parser/DB type section names that xhprof/xdebug can't handle
+ * Arbitrary section name based PHP profiling. This custom profiler can track
+ * code execution that doesn't cleanly map to a function call and thus can't be
+ * handled by Xhprof or Excimer. For example, parser invocations or DB queries.
  *
  * @since 1.25
+ * @ingroup Profiler
  */
 class SectionProfiler {
 	/** @var array Map of (mem,real,cpu) */

includes/profiler/output/ProfilerOutput.php

@@ -16,13 +16,13 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Profiler
  */
 
 /**
- * Base class for profiling output
+ * Base class for profiling output.
  *
- * Since 1.25
+ * @ingroup Profiler
+ * @since 1.25
  */
 abstract class ProfilerOutput {
 	/** @var Profiler */

includes/profiler/output/ProfilerOutputDump.php

@@ -1,7 +1,5 @@
 <?php
 /**
- * Profiler dumping output in xhprof dump file
- *
  * 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
@@ -18,13 +16,12 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Profiler
  */
 
 /**
- * Profiler dumping output in xhprof dump file
- * @ingroup Profiler
+ * Dump profiler data in a ".xhprof" file.
  *
+ * @ingroup Profiler
  * @since 1.25
  * @property ProfilerXhprof $collector
  */

includes/profiler/output/ProfilerOutputStats.php

@@ -1,8 +1,5 @@
 <?php
 /**
- * ProfilerOutput class that flushes profiling data to the profiling
- * context's stats buffer.
- *
  * 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,13 +16,11 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Profiler
  */
 use MediaWiki\MediaWikiServices;
 
 /**
- * ProfilerOutput class that flushes profiling data to the profiling
- * context's stats buffer.
+ * Flush profiling data to StatsD.
  *
  * @ingroup Profiler
  * @since 1.25

includes/profiler/output/ProfilerOutputText.php

@@ -1,7 +1,5 @@
 <?php
 /**
- * Profiler showing output in page source.
- *
  * 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
@@ -18,11 +16,12 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Profiler
  */
 
 /**
- * The least sophisticated profiler output class possible, view your source! :)
+ * Adds profiler output to the HTTP response.
+ *
+ * The least sophisticated profiler output class possible, view source! :)
  *
  * @ingroup Profiler
  * @since 1.25