From 7f9c5ffeef9cac0219e8d3f942b51df12e7808c2 Mon Sep 17 00:00:00 2001
From: Nils Adermann <naderman@naderman.de>
Date: Mon, 21 May 2012 18:26:18 +0200
Subject: [PATCH] Add documentation to RuleWatchChain and RuleWatchNode

---
 .../DependencyResolver/RuleWatchChain.php     | 18 ++++++++++
 .../DependencyResolver/RuleWatchNode.php      | 33 ++++++++++++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/src/Composer/DependencyResolver/RuleWatchChain.php b/src/Composer/DependencyResolver/RuleWatchChain.php
index 00ff0bc56..2fea0d6ee 100644
--- a/src/Composer/DependencyResolver/RuleWatchChain.php
+++ b/src/Composer/DependencyResolver/RuleWatchChain.php
@@ -13,18 +13,36 @@
 namespace Composer\DependencyResolver;
 
 /**
+ * An extension of SplDoublyLinkedList with seek and removal of current element
+ *
+ * SplDoublyLinkedList only allows deleting a particular offset and has no
+ * method to set the internal iterator to a particular offset.
+ *
  * @author Nils Adermann <naderman@naderman.de>
  */
 class RuleWatchChain extends \SplDoublyLinkedList
 {
     protected $offset = 0;
 
+    /**
+     * Moves the internal iterator to the specified offset
+     *
+     * @param int $offset The offset to seek to.
+     */
     public function seek($offset)
     {
         $this->rewind();
         for ($i = 0; $i < $offset; $i++, $this->next());
     }
 
+    /**
+     * Removes the current element from the list
+     *
+     * As SplDoublyLinkedList only allows deleting a particular offset and
+     * incorrectly sets the internal iterator if you delete the current value
+     * this method sets the internal iterator back to the following element
+     * using the seek method.
+     */
     public function remove()
     {
         $offset = $this->key();
diff --git a/src/Composer/DependencyResolver/RuleWatchNode.php b/src/Composer/DependencyResolver/RuleWatchNode.php
index c0a2258e6..4bdeaade2 100644
--- a/src/Composer/DependencyResolver/RuleWatchNode.php
+++ b/src/Composer/DependencyResolver/RuleWatchNode.php
@@ -13,6 +13,10 @@
 namespace Composer\DependencyResolver;
 
 /**
+ * Wrapper around a Rule which keeps track of the two literals it watches
+ *
+ * Used by RuleWatchGraph to store rules in two RuleWatchChains.
+ *
  * @author Nils Adermann <naderman@naderman.de>
  */
 class RuleWatchNode
@@ -22,6 +26,11 @@ class RuleWatchNode
 
     protected $rule;
 
+    /**
+     * Creates a new node watching the first and second literals of the rule.
+     *
+     * @param Rule $rule The rule to wrap
+     */
     public function __construct($rule)
     {
         $this->rule = $rule;
@@ -33,7 +42,12 @@ class RuleWatchNode
     }
 
     /**
-     * Put watch2 on rule's literal with highest level
+     * Places the second watch on the rule's literal, decided at the highest level
+     *
+     * Useful for learned rules where the literal for the highest rule is most
+     * likely to quickly lead to further decisions.
+     *
+     * @param SplFixedArray $decisionMap A package to decision lookup table
      */
     public function watch2OnHighest($decisionMap)
     {
@@ -56,11 +70,22 @@ class RuleWatchNode
         }
     }
 
+    /**
+     * Returns the rule this node wraps
+     *
+     * @return Rule
+     */
     public function getRule()
     {
         return $this->rule;
     }
 
+    /**
+     * Given one watched literal, this method returns the other watched literal
+     *
+     * @param int The watched literal that should not be returned
+     * @return int A literal
+     */
     public function getOtherWatch($literal)
     {
         if ($this->watch1 == $literal) {
@@ -70,6 +95,12 @@ class RuleWatchNode
         }
     }
 
+    /**
+     * Moves a watch from one literal to another
+     *
+     * @param int $from The previously watched literal
+     * @param int $to The literal to be watched now
+     */
     public function moveWatch($from, $to)
     {
         if ($this->watch1 == $from) {