some docs

src/main/java/org/polystat/far/Reverses.java

@@ -60,7 +60,8 @@
 public final class Reverses {
 
     /**
-     * The XMIR of the code.
+     * The XMIR of the code (most probably the implementation is
+     * an instance of class {@link org.polystat.XMIR}).
      */
     private final UncheckedFunc<String, XML> xmir;
 

src/main/resources/org/polystat/far/data-to-attrs.xsl

@@ -23,6 +23,16 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" id="data-to-attrs" version="2.0">
+  <!--
+  This XSL takes all constants (data) anywhere in the object
+  and turns them into bound attributes. Each new attributes
+  gets a name that starts with a &#x3BA; and ends with a
+  unique number.
+
+  We need this because we want to turn the object into
+  a functional aggregate, which be definition consists of functions
+  and variables (no data, no constants).
+  -->
   <xsl:strip-space elements="*"/>
   <xsl:template match="o[o[@name='@']]">
     <xsl:copy>

src/main/resources/org/polystat/far/expected.xsl

@@ -23,6 +23,12 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" id="expected" version="2.0">
+  <!--
+  This XSL expects a parameter $expected, which it adds
+  to the XML element /o/@expected. The value is what the
+  object is expected to become with a certain combination
+  of its free attributes.
+  -->
   <xsl:strip-space elements="*"/>
   <xsl:param name="expected"/>
   <xsl:template match="/o">

src/main/resources/org/polystat/far/reverses.xsl

@@ -23,6 +23,37 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" id="reverses" version="2.0">
+  <!--
+  This XSL goes through all free attributes of each abstract
+  object and adds <opts> elements to them.
+
+  If this is the input:
+  <o name="foo">
+    <o name="a"/>
+    <o name="@">
+      <o base="fun">
+        <o base="a"/>
+      </o>
+    </o>
+  </o>
+
+  The output will look like this:
+  <o name="foo">
+    <o name="a">
+      <opts>
+        <r f="fun" pos="1" tau="1"/>
+      </opts>
+    </o>
+    <o name="@">
+      <o base="fun">
+        <o base="a"/>
+      </o>
+    </o>
+  </o>
+
+  There will be as many <opts> elements as many times the attribute
+  is seen in the body of the object.
+  -->
   <xsl:strip-space elements="*"/>
   <xsl:template name="r">
     <xsl:param name="result" select="''"/>