Improve documentation according to ldoc

site.moon

@@ -74,7 +74,9 @@ template = [[
 </section>
 ]]
 
--- setup in create function:
+--- creates a list of post links for rendering in templates.
+-- @usage
+-- set up in create function:
 --
 -- sitegen.create =>
 --   @list_posts = list_posts @, [template]
@@ -83,6 +85,13 @@ template = [[
 --
 -- `list_posts @` expects $(list_posts({limit = 2}))[[<p>$title</p>]]
 -- `list_posts @, template` expects $each{list_posts({limit = 2}), "post"}[[$post]]
+--
+-- @tparam Page @ the calling page.
+-- @tparam[opt] string template a string that can contain variables and
+-- helpers.
+--
+-- @treturn func the function that will be called when this is used in a
+-- template.
 list_posts = (template) => (args={}) =>
   pages = @site\query_pages { is_a: "post" }
   table.sort pages, (a, b) -> a.source > b.source