Added doc comments on Salmon magicsig-related stuff to help in figuring out what's going on

plugins/OStatus/lib/magicenvelope.php

@@ -81,6 +81,14 @@ class MagicEnvelope
     }
 
 
+    /**
+     *
+     * @param <type> $text
+     * @param <type> $mimetype
+     * @param <type> $keypair
+     * @return array: associative array of envelope properties
+     * @fixme it might be easier to work with storing envelope data these in the object instead of passing arrays around
+     */
     public function signMessage($text, $mimetype, $keypair)
     {
         $signature_alg = Magicsig::fromString($keypair);
@@ -95,6 +103,13 @@ class MagicEnvelope
         );
     }
 
+    /**
+     * Create an <me:env> XML representation of the envelope.
+     *
+     * @param array $env associative array with envelope data
+     * @return string representation of XML document
+     * @fixme it might be easier to work with storing envelope data these in the object instead of passing arrays around
+     */
     public function toXML($env) {
         $xs = new XMLStringer();
         $xs->startXML();
@@ -110,6 +125,16 @@ class MagicEnvelope
         return $string;
     }
 
+    /**
+     * Extract the contained XML payload, and insert a copy of the envelope
+     * signature data as an <me:provenance> section.
+     *
+     * @param array $env associative array with envelope data
+     * @return string representation of modified XML document
+     *
+     * @fixme in case of XML parsing errors, this will spew to the error log or output
+     * @fixme it might be easier to work with storing envelope data these in the object instead of passing arrays around
+     */
     public function unfold($env)
     {
         $dom = new DOMDocument();
@@ -136,6 +161,14 @@ class MagicEnvelope
         return $dom->saveXML();
     }
 
+    /**
+     * Find the author URI referenced in the given Atom entry.
+     *
+     * @param string $text string containing Atom entry XML
+     * @return mixed URI string or false if XML parsing fails, or null if no author URI can be found
+     *
+     * @fixme XML parsing failures will spew to error logs/output
+     */
     public function getAuthor($text) {
         $doc = new DOMDocument();
         if (!$doc->loadXML($text)) {
@@ -153,11 +186,30 @@ class MagicEnvelope
         }
     }
 
+    /**
+     * Check if the author in the Atom entry fragment claims to match
+     * the given identifier URI.
+     *
+     * @param string $text string containing Atom entry XML
+     * @param string $signer_uri
+     * @return boolean
+     */
     public function checkAuthor($text, $signer_uri)
     {
         return ($this->getAuthor($text) == $signer_uri);
     }
 
+    /**
+     * Attempt to verify cryptographic signing for parsed envelope data.
+     * Requires network access to retrieve public key referenced by the envelope signer.
+     *
+     * Details of failure conditions are dumped to output log and not exposed to caller.
+     *
+     * @param array $env array representation of magic envelope data, as returned from MagicEnvelope::parse()
+     * @return boolean
+     *
+     * @fixme it might be easier to work with storing envelope data these in the object instead of passing arrays around
+     */
     public function verify($env)
     {
         if ($env['alg'] != 'RSA-SHA256') {
@@ -190,12 +242,32 @@ class MagicEnvelope
         return $verifier->verify($env['data'], $env['sig']);
     }
 
+    /**
+     * Extract envelope data from an XML document containing an <me:env> or <me:provenance> element.
+     *
+     * @param string XML source
+     * @return mixed associative array of envelope data, or false on unrecognized input
+     *
+     * @fixme it might be easier to work with storing envelope data these in the object instead of passing arrays around
+     * @fixme will spew errors to logs or output in case of XML parse errors
+     * @fixme may give fatal errors if some elements are missing or invalid XML
+     * @fixme calling DOMDocument::loadXML statically triggers warnings in strict mode
+     */
     public function parse($text)
     {
         $dom = DOMDocument::loadXML($text);
         return $this->fromDom($dom);
     }
 
+    /**
+     * Extract envelope data from an XML document containing an <me:env> or <me:provenance> element.
+     *
+     * @param DOMDocument $dom
+     * @return mixed associative array of envelope data, or false on unrecognized input
+     *
+     * @fixme it might be easier to work with storing envelope data these in the object instead of passing arrays around
+     * @fixme may give fatal errors if some elements are missing
+     */
     public function fromDom($dom)
     {
         $env_element = $dom->getElementsByTagNameNS(MagicEnvelope::NS, 'env')->item(0);