CI: Add documentation to XSLT files for Sparkle Appcast action

.github/actions/sparkle-appcast/appcast_adjust.xslt

@@ -5,18 +5,39 @@ xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
 <xsl:output method="xml" encoding="UTF-8" omit-xml-declaration="no"/>
 <xsl:strip-space elements="*"/>
 
+<!-- Select /rss/channel/title and store it as default value for 'pCustomTitle' -->
 <xsl:param name="pCustomTitle" select="/rss/channel/title" />
+<!-- Select /rss/channel/link and store it as default value for 'pCustomLink' -->
 <xsl:param name="pCustomLink" select="/rss/channel/link" />
+<!-- Set empty strings as default values for pSparkleUrl and pDeltaUrl -->
 <xsl:param name="pSparkleUrl" select="''" />
 <xsl:param name="pDeltaUrl" select="''" />
 
+<!-- XSLT identity rule - copy all nodes and their child nodes as well as attributes
+     (attributes are _not_ descendants of the nodes they belong to).
+     This copy rule is applied as the "default" transformation for all nodes.
+-->
 <xsl:template match="@* | node()">
     <xsl:copy>
         <xsl:apply-templates select="@* | node()" />
     </xsl:copy>
 </xsl:template>
+<!-- Match the <title> under <channel> and <rss> and do not translate it
+     (effectively removes it).
+-->
 <xsl:template match="/rss/channel/title" />
+<!-- Match the <link> under <channel> and <rss> and do not translate it
+     (effectively removes it).
+ -->
 <xsl:template match="/rss/channel/link" />
+<!-- Match the <channel> under <rss> and apply a copy translation, which
+     * Creates a new <title> element with a text child node and the text content
+       of the pCustomTitle variable
+     * Creates a new <link> element with a text child node and the text content
+       of the pCustomLink variable
+     * Copies all child nodes and attributes of the original <channel> node
+       (this is why <title> and <link> were explicitly not translated before)
+-->
 <xsl:template match="/rss/channel">
     <xsl:copy>
         <xsl:element name="title"><xsl:value-of select="$pCustomTitle" /></xsl:element>
@@ -24,6 +45,18 @@ xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
         <xsl:apply-templates select="@* | node()" />
     </xsl:copy>
 </xsl:template>
+<!-- Match every url attribute of <enclosure> nodes in <sparkle:deltas> nodes
+     (which themselves are under <item>, <channel>, and <rss> nodes respectively).
+
+     Create a new attribute with the name "url" and then set its content to either
+     * The original value of the attribute if it starts with the value of the
+       pDeltaUrl variable, OR
+     * The actual value of the pDeltaUrl variable, with the value of the
+       pSparkleUrl variable removed in front of the current url value added after
+
+     This effectively updates every url attribute on a delta <enclosure> node
+     that does not start with the current delta url path.
+-->
 <xsl:template match="/rss/channel/item/sparkle:deltas/enclosure/@url">
     <xsl:attribute name="url">
         <xsl:choose>
@@ -37,6 +70,11 @@ xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
         </xsl:choose>
     </xsl:attribute>
 </xsl:template>
+<!-- Match any <sparkle:fullReleaseNotesLink> node under <item>, <channel>,
+     and <rss> respectively, and replace it with a new node named
+     <sparkle:releaseNotesLink> and populate it with all child nodes and
+        attributes of the original node.
+-->
 <xsl:template match="/rss/channel/item/sparkle:fullReleaseNotesLink">
     <xsl:element name="sparkle:releaseNotesLink"><xsl:apply-templates select="@* | node()" /></xsl:element>
 </xsl:template>

.github/actions/sparkle-appcast/appcast_legacy.xslt

@@ -5,12 +5,29 @@ xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
 <xsl:output method="xml" encoding="UTF-8" omit-xml-declaration="no"/>
 <xsl:strip-space elements="*"/>
 
+<!-- XSLT identity rule - copy all nodes and their child nodes as well as attributes
+     (attributes are _not_ descendants of the nodes they belong to).
+     This copy rule is applied as the "default" transformation for all nodes.
+-->
 <xsl:template match="@* | node()">
     <xsl:copy>
         <xsl:apply-templates select="@* | node()" />
     </xsl:copy>
 </xsl:template>
+<!-- Select every <item> node under a <channel> and <rss> node respectively,
+     which has a <sparkle:channel> child node whose text child node's value
+     is not equal to 'stable', then apply to translation, effectively removing
+     it.
+-->
 <xsl:template match="/rss/channel/item[sparkle:channel[text()!='stable']]" />
+<!-- Select every <sparkle:channel> node under a <item> node which sits under a
+     <channel> and <rss> node respectively, then apply no translation, effectively
+     removing it.
+-->
 <xsl:template match="/rss/channel/item/sparkle:channel" />
+<!-- Select every <sparkle:deltas> node under a <item> node which sits under a
+     <channel> and <rss> node respectively, then apply no translation, effectively
+     removing it.
+-->
 <xsl:template match="/rss/channel/item/sparkle:deltas" />
 </xsl:stylesheet>