Doxygen-commenting blog.py, and content.py.

1 files changed, 36 insertions, 9 deletions

diff --git a/talerblog/blog/content.py b/talerblog/blog/content.py
index 4aeb865..8dddd1f 100644
--- a/talerblog/blog/content.py
+++ b/talerblog/blog/content.py
@@ -1,3 +1,4 @@
+##
 # This file is part of GNU TALER.
 # Copyright (C) 2014-2016 INRIA
 #
@@ -13,10 +14,7 @@
 # GNU TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 #
 # @author Florian Dold
-
-"""
-Define content and associated metadata that is served on the blog.
-"""
+# @brief Define content and associated metadata that is served on the blog.
 
 from collections import OrderedDict, namedtuple
 import logging
@@ -29,27 +27,56 @@ LOGGER = logging.getLogger(__name__)
 NOISY_LOGGER = logging.getLogger("chardet.charsetprober")
 NOISY_LOGGER.setLevel(logging.INFO)
 Article = namedtuple("Article", "slug title teaser main_file extra_files")
-ARTICLES = OrderedDict()
 
+##
+# @var if a article is added to this list, then it will
+#      be made available in the blog.
+ARTICLES = OrderedDict()
 
+##
+# Add article to the list of the available articles.
+#
+# @param slug article's title with all the spaces converted to underscores.
+# @param title article's title.
+# @param teaser a short description of the main article's content.
+# @param main_file path to the article's HTML file.
+# @param extra_file collection of extra files associated with the
+#        article, like images and sounds.
 def add_article(slug, title, teaser, main_file, extra_files):
     ARTICLES[slug] = Article(slug, title, teaser, main_file, extra_files)
 
 
+##
+# Build the file path of a image.
+#
+# @param image the image filename.
+# @return the path to the image file.
 def get_image_file(image):
     filex = resource_filename("talerblog", os.path.join("blog/data/", image))
     return os.path.abspath(filex)
 
-
+##
+# Build the file path of a article.
+#
+# @param article the article filename.
+# @return the path to the article HTML file.
 def get_article_file(article):
     filex = resource_filename("talerblog", article.main_file)
     return os.path.basename(filex)
 
 
+##
+# Extract information from HTML file, and use these informations
+# to make the article available in the blog.
+#
+# @param resource_name path to the (HTML) article.
+# @param teaser_paragraph position of the teaser paragraph in the
+#        article's list of all the P tags.  Defaults to zero, as normally
+#        this information is found under the very first P tag.
+# @param title article's title; normally, this bit is extracted from the
+#        HTML itself, so give it here if a explicit title needs to be
+#        specified.
 def add_from_html(resource_name, teaser_paragraph=0, title=None):
-    """
-    Extract information from article html.
-    """
     res = resource_stream("talerblog", resource_name)
     soup = BeautifulSoup(res, 'html.parser')
     res.close()