Updates to metadata service docs

PLUGINS.md

@@ -53,13 +53,6 @@ mismatch._
 
 ## Plugin Dependencies
 
-From your plugins you may import any component of server code relative to the
-project root. An example could be:
-
-```js
-const cache = require('services/cache');
-```
-
 You may also include additional external depenancies in your local packages by
 specifying a `package.json` at your plugin root which will result in a
 `node_modules` folder being generated at the plugin root with your specific
@@ -67,6 +60,16 @@ dependencies.
 
 ## Server Plugins
 
+### API
+
+You can access any API available inside the talk directory in a plugin by simply
+importing the file relative to the talk project root. An example would be if you
+wanted to import the `MetadataService`, you would simply write:
+
+```javascript
+const MetadataService = require('services/metadata');
+```
+
 ### Specification
 
 Each plugin should export a single object with all hooks available on it.

services/metadata.js

@@ -36,7 +36,14 @@ class MetadataService {
   }
 
   /**
-   * Sets an object on the metadata field of an object.
+   * Sets an object on the metadata field of an object. An example could be:
+   *
+   * @example
+   * const MetadataService = require('services/metadata');
+   * const CommentModel = require('models/comment');
+   *
+   * // Sets the property `loaded` on the comment with `id=1`.
+   * MetadataService.set(CommentModel, '1', 'loaded', true);
    *
    * @static
    * @param {mongoose.Model} model the mongoose model for the object
@@ -60,6 +67,13 @@ class MetadataService {
   /**
    * Removes the value for the metadata field as the specific key.
    *
+   * @example
+   * const MetadataService = require('services/metadata');
+   * const CommentModel = require('models/comment');
+   *
+   * // Removes the property `loaded` on the comment with `id=1`.
+   * MetadataService.unset(CommentModel, '1', 'loaded');
+   *
    * @static
    * @param {mongoose.Model} model the mongoose model for the object
    * @param {String} id the value for the field `id` of the model