diff --git a/doc/preferences.md b/doc/preferences.md
index 0b81e5982..cff8734dc 100644
--- a/doc/preferences.md
+++ b/doc/preferences.md
@@ -18,7 +18,7 @@ settings are this:
     type=ini
 
 The ini provider uses the directory **config/preferences** to create one ini
-file per user and persists the data into a single file. If your want to drop your
+file per user and persists the data into a single file. If you want to drop your
 preferences just drop the file from disk and you'll start with a new profile.
 
 ## Database provider
@@ -68,13 +68,13 @@ database and a writable user you need to import the initial table file:
     mysql> exit
     # mysql -u root -p icingaweb < /path/to/icingaweb/etc/schema/preferences.mysql.sql
 
-After following this steps above you can configure your preferences provider.
+After following these steps above you can configure your preferences provider.
 
 ## Coding API
 
-Preferenecs are controlled by the Preferences object which was injected into the
-User object on application start (You do not have to think about). For example
-if you have gathered the user object:
+You can set, update or remove preferences using the Preference data object
+which is bound to the user. Here are some simple examples how to work with
+that:
 
     $preferences = $user->getPreferences();
     // Get language with en_US as fallback
diff --git a/library/Icinga/User/Preferences.php b/library/Icinga/User/Preferences.php
index 030a4571e..7df363641 100644
--- a/library/Icinga/User/Preferences.php
+++ b/library/Icinga/User/Preferences.php
@@ -78,13 +78,10 @@ class Preferences implements SplSubject, \Countable
     }
 
     /**
-     * (PHP 5 &gt;= 5.1.0)<br/>
      * Attach an SplObserver
+     *
      * @link http://php.net/manual/en/splsubject.attach.php
-     * @param SplObserver $observer <p>
-     * The <b>SplObserver</b> to attach.
-     * </p>
-     * @return void
+     * @param SplObserver $observer
      */
     public function attach(SplObserver $observer)
     {
@@ -92,13 +89,10 @@ class Preferences implements SplSubject, \Countable
     }
 
     /**
-     * (PHP 5 &gt;= 5.1.0)<br/>
      * Detach an observer
+     *
      * @link http://php.net/manual/en/splsubject.detach.php
-     * @param SplObserver $observer <p>
-     * The <b>SplObserver</b> to detach.
-     * </p>
-     * @return void
+     * @param SplObserver $observer
      */
     public function detach(SplObserver $observer)
     {
@@ -109,10 +103,9 @@ class Preferences implements SplSubject, \Countable
     }
 
     /**
-     * (PHP 5 &gt;= 5.1.0)<br/>
      * Notify an observer
+     *
      * @link http://php.net/manual/en/splsubject.notify.php
-     * @return void
      */
     public function notify()
     {
@@ -124,13 +117,10 @@ class Preferences implements SplSubject, \Countable
     }
 
     /**
-     * (PHP 5 &gt;= 5.1.0)<br/>
      * Count elements of an object
+     *
      * @link http://php.net/manual/en/countable.count.php
-     * @return int The custom count as an integer.
-     * </p>
-     * <p>
-     * The return value is cast to an integer.
+     * @return int The custom count as an integer
      */
     public function count()
     {