From 404b91129ed945780fe5b34d6d17c8e1c7a1301b Mon Sep 17 00:00:00 2001
From: jensp <jensp@8810af33-2d31-482b-a856-94f89814c4df>
Date: Mon, 21 Oct 2019 18:49:39 +0000
Subject: [PATCH] Documentation for the Freemarker function libs provided by
 ccm-themedirectory

git-svn-id: https://svn.libreccm.org/ccm/trunk@6279 8810af33-2d31-482b-a856-94f89814c4df
---
 .../web/themes/freemarker/language.ftl        |  3 +-
 .../web/themes/freemarker/utils.ftl           | 37 +++++++++++++++++--
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/ccm-themedirector/web/themes/freemarker/language.ftl b/ccm-themedirector/web/themes/freemarker/language.ftl
index 388d6988c..c429a1fd1 100644
--- a/ccm-themedirector/web/themes/freemarker/language.ftl
+++ b/ccm-themedirector/web/themes/freemarker/language.ftl
@@ -6,7 +6,8 @@
 >
 
 <#---
-    Retrieves the languages in which the content of the current page is available.
+    Retrieves the languages in which the content of the current page is 
+    available.
 
     @return A sequence of the available languages (as ISO language codes)
 #-->
diff --git a/ccm-themedirector/web/themes/freemarker/utils.ftl b/ccm-themedirector/web/themes/freemarker/utils.ftl
index 343313d33..cf60e7e33 100644
--- a/ccm-themedirector/web/themes/freemarker/utils.ftl
+++ b/ccm-themedirector/web/themes/freemarker/utils.ftl
@@ -5,26 +5,46 @@
 "ui": "http://www.arsdigita.com/ui/1.0"}
 >
 
-<#--
-    Gets the application of the page served from the model
+<#---
+    Gets the application of the page served from the model.
+
+    @return The current application.
 -->
 <#function getPageApplication>
     <#return model["/bebop:page/@application"]>
 </#function>
 
+<#---
+    Get the title of the current page.
+
+    This will only work of the current page is a navigation page with a category 
+    menu.
+
+    @return The title of the current page
+-->
 <#function getPageTitle>
     <#return model["//nav:categoryMenu/nav:category/@title"]>
 </#function>
 
+<#---
+    Get the hostname from the sitebanner data.
+-->
 <#function getSiteHostName>
     <#return model["/bebop:page/ui:siteBanner/@hostname"]>
 </#function>
 
+<#---
+    Get the name of the site from the sitebanner data.
+-->
 <#function getSiteName>
     <#return model["/bebop:page/ui:siteBanner/@sitename"]>
 </#function>
 
-<#-- Internal function -->
+<#-- 
+    Internal function. Not for public use.
+    Internal function for coverting several string values like `yes`, `true`, 
+    `no` etc. to a boolean value. 
+-->
 <#function getBooleanAttrValue fromNode attrName>
     <#assign path='@' + attrName>
     <#if (fromNode[path]?size > 0)>
@@ -35,6 +55,17 @@
     </#if>
 </#function>
 
+<#---
+    A wrapper for the `_formatDateTime` function which adds missing numbers.
+    `_formatDateTime` uses Java APIs for formatting which don't work well with
+    incomplete dates. This function takes a date from the data model and checks
+    if a component (year, month, day, hour, minute, second) is missing. If the
+    the component is missing the function adds uses a default value of that
+    component.
+
+    @param style The date format style from the theme manifest to use.
+    @param date the date to format.
+-->
 <#function formatDateTime style date>
     <#assign year   = (date["./@year"]?size > 0)?then(date["./@year"]?number, 0)>
     <#assign month  = (date["./@month"]?size > 0)?then(date["./@month"]?number, 0)>