Monday, 11 January 2010

Documenting Clojure Code

As I begin to write Clojure code, I want to make sure I document it correctly. Looking at some source I can see the following (from http://github.com/richhickey/clojure-contrib/blob/master/src/clojure/contrib/core.clj):
(ns
  #^{:author "Laurent Petit (and others)"
     :doc "Functions/macros variants of the ones that can be found in clojure.core 
 (note to other contrib members: feel free to add to this lib)"}
  clojure.contrib.core
  (:use clojure.contrib.def))

(defn new-by-name
  "Constructs a Java object whose class is specified by a String."
  [class-name & args]
  (clojure.lang.Reflector/invokeConstructor
   (clojure.lang.RT/classForName class-name)
   (into-array Object args)))
There is some meta data in the namespace declaration, and a documentation string in the function definition. This is what I should look to emulate. ":doc" must be a standard meta-data label. Yep - page 57 of Programming Clojure confirms it. Others include:
  • :arglists - Parameter info used by doc
  • :doc - Documentation used by doc
  • :file - Source file
  • :line - Source line number
  • :macro - True for macros
  • :name - Local name
  • :ns - Namespace
  • :tag - Expected argument or return type

No comments:

Post a Comment