Issue #2216563 by jhodgdon: Fill in @defgroup/topic docs for Object Oriented Programming overview.

core/modules/system/core.api.php

@@ -1247,16 +1247,33 @@
  * @{
  * PSR-4, namespaces, class naming, and other conventions.
  *
- * @todo write this
- *
- * Additional documentation paragraphs need to be written, and functions,
- * classes, and interfaces need to be added to this topic.
- *
- * See https://drupal.org/node/608152 and links therein for references. This
- * should be an overview and link to details. It needs to cover: PSR-*,
- * namespaces, link to reference on OO, class naming conventions (base classes,
- * etc.), and other things developers should know related to object-oriented
- * coding.
+ * A lot of the PHP code in Drupal is object oriented (OO), making use of
+ * @link http://php.net/manual/language.oop5.php PHP classes, interfaces, and traits @endlink
+ * (which are loosely referred to as "classes" in the rest of this topic). The
+ * following conventions and standards apply to this version of Drupal:
+ * - Each class must be in its own file.
+ * - Classes must be namespaced. If a module defines a class, the namespace
+ *   must start with \Drupal\module_name. If it is defined by Drupal Core for
+ *   use across many modules, the namespace should be \Drupal\Core or
+ *   \Drupal\Component, with the exception of the global class \Drupal. See
+ *   https://www.drupal.org/node/1353118 for more about namespaces.
+ * - In order for the PSR-4-based class auto-loader to find the class, it must
+ *   be located in a directory corresponding to the namespace. For
+ *   module-defined classes, if the namespace is \Drupal\module_name\foo\bar,
+ *   then the class goes under the main module directory in directory
+ *   src/foo/bar. For Drupal-wide classes, if the namespace is
+ *   \Drupal\Core\foo\bar, then it goes in directory
+ *   core/lib/Drupal/Core/foo/bar. See https://www.drupal.org/node/2156625 for
+ *   more information about PSR-4.
+ * - Some classes have annotations added to their documentation headers. See
+ *   the @link annotation Annotation topic @endlink for more information.
+ * - Standard plugin discovery requires particular namespaces and annotation
+ *   for most plugin classes. See the
+ *   @link plugin_api Plugin API topic @endlink for more information.
+ * - There are project-wide coding standards for OO code, including naming:
+ *   https://drupal.org/node/608152
+ * - Documentation standards for classes are covered on:
+ *   https://www.drupal.org/coding-standards/docs#classes
  * @}
  */