Change namespaces and add docstrings

README.md

@@ -33,7 +33,7 @@ Above HTML will be converted to following and vice versa.
 
 ## Usage
 ### As a library
-Add `[hicv "1.0.0-SNAPSHOT"]` to your project dependencies, then:
+Add `[hiccup-bridge "1.0.0-SNAPSHOT"]` to your project dependencies, then:
 
 ```clojure
 (use '[to-hiccup.core :only [html->hiccup]])
@@ -88,5 +88,5 @@ total 88
 
 ## Installation to Leiningen
 ```bash
-% lein plugin install hicv 1.0.0-SNAPSHOT
+% lein plugin install hiccup-bridge 1.0.0-SNAPSHOT
 ```

project.clj

@@ -1,4 +1,4 @@
-(defproject hicv "1.0.0-SNAPSHOT"
+(defproject hiccup-bridge "1.0.0-SNAPSHOT"
   :description "Hiccup to html, html to hiccup."
   :dependencies [[org.clojure/clojure "1.4.0"]
                  [org.clojars.hozumi/clj-glob "0.1.2"]

src/to_hiccup/core.clj → src/hiccup_bridge/core.clj

@@ -1,4 +1,4 @@
-(ns to-hiccup.core
+(ns hiccup-bridge.core
   "Convert html into hiccup and vice verse"
   (:require [net.cgrand.enlive-html :as en]
             [hiccup.core :as hic]
@@ -9,34 +9,46 @@
 
 (def ^{:private true} hicv-dir-name "hicv")
 
-(defn ensure-hicv-dir! []
+(defn ensure-hicv-dir!
+  "Make sure that hicv/ directory exist by creating it when necessary."
+  []
   (let [dir (io/file hicv-dir-name)]
     (if-not (.exists dir)
       (.mkdir dir))))
 
-(defn remove-extension [file-path]
+(defn remove-extension
+  "Remove extension from a file path."
+  [file-path]
   (if-let [[_ pure-file-path] (re-matches #"(.*)\..*" file-path)]
     pure-file-path
     file-path))
 
-(defn replace-extension [file-path extension]
+(defn replace-extension
+  "Replace extension of a file path with a new one."
+  [file-path extension]
   (-> file-path remove-extension (str extension)))
 
-(defn hiccup-file->html-file [file-path]
+(defn hiccup-file->html-file
+  "Do convert a Clojure/hiccup file to an HTML one."
+  [file-path]
   (spit (replace-extension file-path ".html")
         (-> (slurp file-path :encoding (enc/detect file-path :default))
             read-string
             hic/html)))
 
-(defn hiccup-files->html-files [file-paths]
+(defn hiccup-files->html-files
+  "Batch convert many Clojure/hiccup files to HTML ones."
+  [file-paths]
   (ensure-hicv-dir!)
   (let [file-paths (if (empty? file-paths)
                      (glob/glob (str hicv-dir-name "/**/*.clj") :s)
                      file-paths)]
     (dorun
      (map hiccup-file->html-file file-paths))))
 
-(defn add-id&classes->tag [tag {:keys [class id]}]
+(defn add-id&classes->tag
+  "Add id and classes to an HTML tag (the hiccup way)."
+  [tag {:keys [class id]}]
   (keyword
    (str (name tag)
         (when id
@@ -46,7 +58,9 @@
                  (interleave (repeat ".")
                              (re-seq #"[^ ]+" class)))))))
 
-(defn enlive-node->hiccup [node]
+(defn enlive-node->hiccup
+  "A parser that makes hiccup data from an enlive node."
+  [node]
   (if (map? node)
     ;; for comment node {:type :comment, :data "[if IE]> ..."}
     (if (= :comment (:type node))
@@ -63,28 +77,35 @@
 (defn url? [s]
   (re-matches #"https?://.*" s))
 
-(defn get-resource [resource-path]
+(defn get-resource
+  [resource-path]
   (if (url? resource-path)
     (java.net.URL. resource-path)
     (io/reader resource-path :encoding (enc/detect resource-path :default))))
 
-(defn html->hiccup [s]
+(defn html->hiccup
+  "Do convert an HTML string to Clojure/hiccup data."
+  [s]
   (let [nodes (-> s
                   java.io.StringReader.
                   en/html-resource)]
     (->> (map enlive-node->hiccup nodes)
          (filter #(not (and (string? %)
                             (re-matches #"\n\s*" %)))))))
 
-(defn html-file->hiccup [resource-path]
+(defn html-file->hiccup
+  "Make Clojure/hiccup data from a HTML file."
+  [resource-path]
   (let [nodes (-> resource-path
                   get-resource
                   en/html-resource)]
     (->> (map enlive-node->hiccup nodes)
          (filter #(not (and (string? %)
                             (re-matches #"\n\s*" %)))))))
 
-(defn ensure-under-hicv-dir [^String resource-path]
+(defn ensure-under-hicv-dir
+  "Check if files passed as command line arguements are under hicv/ directory."
+  [^String resource-path]
   (if (url? resource-path)
     (apply str hicv-dir-name "/" (replace {\/ \_} resource-path))
     (if (.startsWith resource-path hicv-dir-name)
@@ -93,14 +114,19 @@
            (or (re-find #"[^/]*$" resource-path) ;;"/ab/cd.html" => "cd.html"
                "out.html")))))
 
-(defn html-file->hiccup-file [resource-path]
+(defn html-file->hiccup-file
+  "Do convert a html file to a Clojure/hiccup one (using io stream
+  so if you want to convert strings, use html->hiccup instead)."
+  [resource-path]
   (spit (replace-extension (ensure-under-hicv-dir resource-path) ".clj")
         (-> resource-path
             html-file->hiccup
             pp/pprint
             with-out-str)))
 
-(defn html-files->hiccup-files [resource-paths]
+(defn html-files->hiccup-files
+  "Batch convert many HTML files to Clojure/hiccup ones."
+  [resource-paths]
   (ensure-hicv-dir!)
   (let [resource-paths (if (empty? resource-paths)
                          (glob/glob (str hicv-dir-name "/**/*.html") :s)

test/to_hiccup/test/core.clj → test/hiccup_bridge/test/core.clj

@@ -1,6 +1,6 @@
-(ns to-hiccup.test.core
+(ns hiccup-bridge.test.core
   (:use clojure.test
-        to-hiccup.core))
+        hiccup-bridge.core))
 
 (deftest replace-extension-test
   (is (= "hicv/aaa.html"