diff --git a/lib/public/api.php b/lib/public/api.php
index d94b68e908a58680373cda50d4335e0821431cee..afee2988635e52d611a97b2c7ecf904f8e1bc780 100644
--- a/lib/public/api.php
+++ b/lib/public/api.php
@@ -20,6 +20,14 @@
 *
 */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * API Class
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/app.php b/lib/public/app.php
index 18681670ddddfff53e8835f307f0ba51ef65cdc9..9680f0df72c34db022eb51c912fb1b1bab7a55f0 100644
--- a/lib/public/app.php
+++ b/lib/public/app.php
@@ -22,7 +22,7 @@
 
 /**
  * Public interface of ownCloud for apps to use.
- * App Class.
+ * App Class
  *
  */
 
diff --git a/lib/public/defaults.php b/lib/public/defaults.php
index 147f23e341f3e583e856962c036429ae4c9939cc..5f908e4c5e78ad91df523c384068505724ba8d1d 100644
--- a/lib/public/defaults.php
+++ b/lib/public/defaults.php
@@ -20,12 +20,19 @@
 *
 */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Defaults Class
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /*
  * public api to access default strings and urls for your templates
  */
-
 class Defaults {
 
 	private $defaults;
diff --git a/lib/public/groupinterface.php b/lib/public/groupinterface.php
index 5603faa8265470d07106e421663a457b349993e2..0a5467f71d6eb236b4bd3aedf5facd480bc8f4bd 100644
--- a/lib/public/groupinterface.php
+++ b/lib/public/groupinterface.php
@@ -26,6 +26,8 @@
  *
  */
 
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 interface GroupInterface extends \OC_Group_Interface {}
diff --git a/lib/public/icache.php b/lib/public/icache.php
index a73004ec9a72fd7bbced4621ed81085e673facf0..7f594d7a77a28689f9e88a0759643c0f4e4b2a83 100644
--- a/lib/public/icache.php
+++ b/lib/public/icache.php
@@ -5,6 +5,15 @@
  * later.
  * See the COPYING-README file.
  */
+
+/**
+ * Public interface of ownCloud for apps to use.
+ * Cache interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/iconfig.php b/lib/public/iconfig.php
index 850bddf6935fce77b22c71b597481f77fb67c8bb..d8ac3ae6fc3ef63ad65c2ef9e0cbee86caf1bad2 100644
--- a/lib/public/iconfig.php
+++ b/lib/public/iconfig.php
@@ -4,9 +4,17 @@
  * This file is licensed under the Affero General Public License version 3 or
  * later.
  * See the COPYING-README file.
- * 
+ *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Config interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/icontainer.php b/lib/public/icontainer.php
index d43c1c90f11dbca405f259a442a3d829cfbae509..6b7052cc4f40fcc3842139049ce3b2a9c41be74a 100644
--- a/lib/public/icontainer.php
+++ b/lib/public/icontainer.php
@@ -20,6 +20,14 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Container interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/idbconnection.php b/lib/public/idbconnection.php
index 252902eda6c2b19c060e64a4528b19bd22be4799..283e6b56271b7634128656a22b23be286bee20d8 100644
--- a/lib/public/idbconnection.php
+++ b/lib/public/idbconnection.php
@@ -7,6 +7,14 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * DBConnection interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/ihelper.php b/lib/public/ihelper.php
index fad02f7556aa41cebde7973a1a8be6faf6494bac..bf07f469f2a22f4787944ad56fd1231c5901e32f 100644
--- a/lib/public/ihelper.php
+++ b/lib/public/ihelper.php
@@ -7,6 +7,14 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Helper interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/il10n.php b/lib/public/il10n.php
index 805c8988aa2340b9539bc65ee57f7b53400b1397..817b299b0b76f6c6b3896e206ef42dce6c7fd4a4 100644
--- a/lib/public/il10n.php
+++ b/lib/public/il10n.php
@@ -7,6 +7,14 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * L10n interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/image.php b/lib/public/image.php
index c6dd9a113ab81a50665ec327d69b81e6d3e4df2d..179c086627c389ab09259646166c889f4eb9de0d 100644
--- a/lib/public/image.php
+++ b/lib/public/image.php
@@ -20,6 +20,14 @@
 *
 */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Image class
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/inavigationmanager.php b/lib/public/inavigationmanager.php
index f89e790c1d0f6bbf70f8cf51db8a12c194781a83..a0be14edc31aa8f934748f4ef5862f894c1a4aff 100644
--- a/lib/public/inavigationmanager.php
+++ b/lib/public/inavigationmanager.php
@@ -4,9 +4,17 @@
  * This file is licensed under the Affero General Public License version 3 or
  * later.
  * See the COPYING-README file.
- * 
+ *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Navigation manager interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/ipreview.php b/lib/public/ipreview.php
index beebd7bd2fae9f912e09cc8c13c5d19489aa170a..4d0405c699012935269d7cf9eba85b91df2e418e 100644
--- a/lib/public/ipreview.php
+++ b/lib/public/ipreview.php
@@ -6,6 +6,15 @@
  * later.
  * See the COPYING-README file.
  */
+
+/**
+ * Public interface of ownCloud for apps to use.
+ * Preview interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/irequest.php b/lib/public/irequest.php
index 45b27868d707f8252e59ee7b2b278d82000a3408..ca23e12b7f5fc200be68b8e0105a45d5ec99f15f 100644
--- a/lib/public/irequest.php
+++ b/lib/public/irequest.php
@@ -20,6 +20,14 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Request interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/iservercontainer.php b/lib/public/iservercontainer.php
index cc9436a75c8237d974ba8579d0903831233ef082..14822817a47506b8099fdb4f431b31c91b0e5bd5 100644
--- a/lib/public/iservercontainer.php
+++ b/lib/public/iservercontainer.php
@@ -20,6 +20,14 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Server container interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 
diff --git a/lib/public/isession.php b/lib/public/isession.php
index 0a77b0c823b042cef5d840bc66723bcf4adc2bea..9daab2fe576c0b7f5d401ad55bee6dc20ab7ec40 100644
--- a/lib/public/isession.php
+++ b/lib/public/isession.php
@@ -8,6 +8,14 @@
  * See the COPYING-README file.
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Session interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/itagmanager.php b/lib/public/itagmanager.php
index 07e1d12fc0f53ee132d3b546d89534b72e7d0743..26623d91a63feb11a7c864a8be86da2988526038 100644
--- a/lib/public/itagmanager.php
+++ b/lib/public/itagmanager.php
@@ -20,6 +20,16 @@
 *
 */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Tag manager interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
+namespace OCP;
+
 /**
  * Factory class creating instances of \OCP\ITags
  *
@@ -30,9 +40,6 @@
  * are entered in. If a user already has a tag 'family' for a type, and
  * tries to add a tag named 'Family' it will be silently ignored.
  */
-
-namespace OCP;
-
 interface ITagManager {
 
 	/**
diff --git a/lib/public/itags.php b/lib/public/itags.php
index 5b1ebd189da25e4fb11ea168eb7a614a9930f5fd..50ea0a59b4623986a31ccf6c2a93d7e04944d04f 100644
--- a/lib/public/itags.php
+++ b/lib/public/itags.php
@@ -20,6 +20,14 @@
 *
 */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * Tags interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 // FIXME: Where should I put this? Or should it be implemented as a Listener?
diff --git a/lib/public/iurlgenerator.php b/lib/public/iurlgenerator.php
index 4eb4c0f83127417175c057cd1e74370c2c23cd0a..6c20734edf01d1b5d44413830c01ea9cd1210e82 100644
--- a/lib/public/iurlgenerator.php
+++ b/lib/public/iurlgenerator.php
@@ -7,6 +7,14 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * URL generator interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/iusersession.php b/lib/public/iusersession.php
index 33d7aeb194c3b4ecc784c5fa80597ccb1e382a2d..3b704f68490e2fa3151d5bd3cccc9c7d2bc65b9d 100644
--- a/lib/public/iusersession.php
+++ b/lib/public/iusersession.php
@@ -7,6 +7,14 @@
  *
  */
 
+/**
+ * Public interface of ownCloud for apps to use.
+ * User session interface
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/share.php b/lib/public/share.php
index 7f4d918757f426c38389efc8b9284dd433438177..01bf61a60a5a33ffe4c004c8e608f15b145fc96a 100644
--- a/lib/public/share.php
+++ b/lib/public/share.php
@@ -18,6 +18,15 @@
  * You should have received a copy of the GNU Affero General Public
  * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
+
+/**
+ * Public interface of ownCloud for apps to use.
+ * Share Class
+ *
+ */
+
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 /**
diff --git a/lib/public/user.php b/lib/public/user.php
index b4931ecc0fa769837d950e88302be4922f7b8ee3..beb82fee03343d8a7e79bd71a199f157472e173c 100644
--- a/lib/public/user.php
+++ b/lib/public/user.php
@@ -22,7 +22,7 @@
 
 /**
  * Public interface of ownCloud for apps to use.
- * User Class.
+ * User Class
  *
  */
 
diff --git a/lib/public/userinterface.php b/lib/public/userinterface.php
index 53d9faf7a5e08e2e75394d07411a988ed49a6029..4c3444d4c219e8b9fd5cdde698786098ce5ed86a 100644
--- a/lib/public/userinterface.php
+++ b/lib/public/userinterface.php
@@ -22,10 +22,12 @@
 
 /**
  * Public interface of ownCloud for apps to use.
- * User Class.
+ * User Interface
  *
  */
 
+// use OCP namespace for all classes that are considered public.
+// This means that they should be used by apps instead of the internal ownCloud classes
 namespace OCP;
 
 interface UserInterface extends \OC_User_Interface {}