diff --git a/project.clj b/project.clj index 054bd6f..098245a 100644 --- a/project.clj +++ b/project.clj @@ -12,8 +12,7 @@ [swank-clojure "1.2.1"] ;;Needed for testing lein plugin [hiccup "0.3.0"] - [org.markdownj/markdownj "0.3.0-1.0.2b4"] - [marginalia "0.5.0-alpha"]] + [org.markdownj/markdownj "0.3.0-1.0.2b4"]] ;;Needed for testing cake plugin :tasks [marginalia.tasks] ;;Needed for testing Latex equation formatting. You must download diff --git a/src/marginalia/core.clj b/src/marginalia/core.clj index 628d3b6..2e13cab 100644 --- a/src/marginalia/core.clj +++ b/src/marginalia/core.clj @@ -1,6 +1,37 @@ +;; ## A new way to think about programs +;; +;; What if your code and its documentation were one and the same? +;; +;; Much of the philosophy guiding literate programming is the realization of the answer to this question. +;; However, if literate programming stands as a comprehensive programming methodology at one of end of the +;; spectrum and no documentation stands as its antithesis, then Marginalia falls somewhere between. That is, +;; you should always aim for comprehensive documentation, but the shortest path to a useful subset is the +;; commented source code itself. +;; +;; ## The art of Marginalia +;; +;; If you’re fervently writing code that is heavily documented, then using Marginalia for your Clojure projects +;; is as simple as running it on your codebase. However, if you’re unaccustomed to documenting your source, then +;; the guidelines herein will help you make the most out of Marginalia for true-power documentation. +;; +;; Following the guidelines will work to make your code not only easier to follow – it will make it better. +;; The very process of using Marginalia will help to crystalize your understanding of problem and its solution(s). +;; +;; The quality of the prose in your documentation will often reflect the quality of the code itself thus highlighting +;; problem areas. The elimination of problem areas will solidify your code and its accompanying prose. Marginalia +;; provides a virtuous circle spiraling inward toward maximal code quality. +;; +;; ## The one true way +;; +;; 1. Start by running Marginalia against your code +;; 2. Cringe at the sad state of your code commentary +;; 3. Add docstrings and code comments as appropriate +;; 4. Generate the documentation again +;; 5. Read the resulting documentation +;; 6. Make changes to code and documentation so that the “dialog” flows sensibly +;; 7. Repeat from step #4 until complete +;; (ns marginalia.core - "**Core** provides all of the functionality around parsing clojure source files - into an easily consumable format." (:require [clojure.java.io :as io] [clojure.string :as str]) (:use [marginalia @@ -12,7 +43,7 @@ (:gen-class)) -(def *test* "./src/cljojo/core.clj") +(def *test* "src/marginalia/core.clj") (def *docs* "./docs") (def *comment* #"^\s*;;\s?") @@ -101,9 +132,15 @@ (defn merge-line [line m] (cond - (:docstring-text line) (assoc m :docs (conj (get m :docs []) line)) - (:code-text line) (assoc m :codes (conj (get m :codes []) line)) - (:docs-text line) (assoc m :docs (conj (get m :docs []) line)))) + (:docstring-text line) (assoc m + :docs + (conj (get m :docs []) line)) + (:code-text line) (assoc m + :codes + (conj (get m :codes []) line)) + (:docs-text line) (assoc m + :docs + (conj (get m :docs []) line)))) (defn group-lines [doc-lines] (loop [cur-group {} @@ -146,7 +183,6 @@ (spit output-file-name source))) ;; ## External Interface (command-line, lein, cake, etc) - (defn format-sources [sources] (if (nil? sources) (find-clojure-file-paths "./src") @@ -162,8 +198,8 @@ "Usage: lein marg ... \n") [[dir d "Directory into which the documentation will be written" "./docs"] [file f "File into which the documentation will be written" "uberdoc.html"] - sources] - (let [sources (format-sources (seq sources))] + src] + (let [sources (format-sources (seq src))] (if-not sources (do (println "Wrong number of arguments passed to marginalia.") diff --git a/src/marginalia/html.clj b/src/marginalia/html.clj index 551bf6f..9dab2f3 100644 --- a/src/marginalia/html.clj +++ b/src/marginalia/html.clj @@ -343,16 +343,16 @@ [:head [:meta {:http-equiv "Content-Type" :content "text/html" :charset "utf-8"}] [:meta {:name "description" :content (:description project-metadata)}] - (inline-js "jquery-1.4.4.min.js") - (inline-js "xregexp-min.js") - (inline-js "shCore.js") - (inline-js "shBrushClojure.js") - (inline-js "app.js") + (inline-js "resources/jquery-1.4.4.min.js") + (inline-js "resources/xregexp-min.js") + (inline-js "resources/shCore.js") + (inline-js "resources/shBrushClojure.js") + (inline-js "resources/app.js") #_[:script {:type "text/javascript" :src "./../resources/app.js"}] - (inline-css "shCore.css") + (inline-css "resources/shCore.css") (css [:.syntaxhighlighter {:overflow "hidden !important"}]) - (inline-css "shThemeEclipse.css") + (inline-css "resources/shThemeEclipse.css") reset-css header-css floating-toc-css diff --git a/src/marginalia/parser.clj b/src/marginalia/parser.clj index eb0360e..7db73e9 100644 --- a/src/marginalia/parser.clj +++ b/src/marginalia/parser.clj @@ -125,7 +125,7 @@ (defmethod dispatch-form 'defmethod [form raw nspace-sym] - (let [ds (nth form 4) + (let [ds (nth form 3) docstring (when (string? ds) ds)] [docstring (strip-docstring docstring raw) diff --git a/src/problem_cases/general.clj b/src/problem_cases/general.clj index e39cb89..30feecf 100644 --- a/src/problem_cases/general.clj +++ b/src/problem_cases/general.clj @@ -79,3 +79,10 @@ \] \{ \})) + +(defmulti kompile identity) + +(defmethod kompile [::standard AutoIncClause] + "This is a docstring. On the left." + [_] + "GENERATED ALWAYS AS IDENTITY")