├── .circleci └── config.yml ├── LICENSE ├── README.md ├── docs └── clojure.core.edn ├── images └── reify.png ├── project.clj ├── src └── nrepl_doc_inject │ └── core.clj └── test └── nrepl_doc_inject └── core_test.clj /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | # Clojure CircleCI 2.0 configuration file 2 | # 3 | # Check https://circleci.com/docs/2.0/language-clojure/ for more details 4 | # 5 | version: 2 6 | jobs: 7 | build: 8 | docker: 9 | # specify the version you desire here 10 | - image: circleci/clojure:lein-2.7.1 11 | 12 | # Specify service dependencies here if necessary 13 | # CircleCI maintains a library of pre-built images 14 | # documented at https://circleci.com/docs/2.0/circleci-images/ 15 | # - image: circleci/postgres:9.4 16 | 17 | working_directory: ~/repo 18 | 19 | environment: 20 | LEIN_ROOT: "true" 21 | # Customize the JVM maximum heap limit 22 | JVM_OPTS: -Xmx3200m 23 | 24 | steps: 25 | - checkout 26 | 27 | # Download and cache dependencies 28 | - restore_cache: 29 | keys: 30 | - v1-dependencies-{{ checksum "project.clj" }} 31 | # fallback to using the latest cache if no exact match is found 32 | - v1-dependencies- 33 | 34 | - run: lein deps 35 | 36 | - save_cache: 37 | paths: 38 | - ~/.m2 39 | key: v1-dependencies-{{ checksum "project.clj" }} 40 | 41 | # run tests! 42 | - run: lein test -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Eclipse Public License - v 1.0 2 | 3 | THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC 4 | LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM 5 | CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. 6 | 7 | 1. DEFINITIONS 8 | 9 | "Contribution" means: 10 | 11 | a) in the case of the initial Contributor, the initial code and documentation 12 | distributed under this Agreement, and 13 | b) in the case of each subsequent Contributor: 14 | i) changes to the Program, and 15 | ii) additions to the Program; 16 | 17 | where such changes and/or additions to the Program originate from and are 18 | distributed by that particular Contributor. A Contribution 'originates' 19 | from a Contributor if it was added to the Program by such Contributor 20 | itself or anyone acting on such Contributor's behalf. Contributions do not 21 | include additions to the Program which: (i) are separate modules of 22 | software distributed in conjunction with the Program under their own 23 | license agreement, and (ii) are not derivative works of the Program. 24 | 25 | "Contributor" means any person or entity that distributes the Program. 26 | 27 | "Licensed Patents" mean patent claims licensable by a Contributor which are 28 | necessarily infringed by the use or sale of its Contribution alone or when 29 | combined with the Program. 30 | 31 | "Program" means the Contributions distributed in accordance with this 32 | Agreement. 33 | 34 | "Recipient" means anyone who receives the Program under this Agreement, 35 | including all Contributors. 36 | 37 | 2. GRANT OF RIGHTS 38 | a) Subject to the terms of this Agreement, each Contributor hereby grants 39 | Recipient a non-exclusive, worldwide, royalty-free copyright license to 40 | reproduce, prepare derivative works of, publicly display, publicly 41 | perform, distribute and sublicense the Contribution of such Contributor, 42 | if any, and such derivative works, in source code and object code form. 43 | b) Subject to the terms of this Agreement, each Contributor hereby grants 44 | Recipient a non-exclusive, worldwide, royalty-free patent license under 45 | Licensed Patents to make, use, sell, offer to sell, import and otherwise 46 | transfer the Contribution of such Contributor, if any, in source code and 47 | object code form. This patent license shall apply to the combination of 48 | the Contribution and the Program if, at the time the Contribution is 49 | added by the Contributor, such addition of the Contribution causes such 50 | combination to be covered by the Licensed Patents. The patent license 51 | shall not apply to any other combinations which include the Contribution. 52 | No hardware per se is licensed hereunder. 53 | c) Recipient understands that although each Contributor grants the licenses 54 | to its Contributions set forth herein, no assurances are provided by any 55 | Contributor that the Program does not infringe the patent or other 56 | intellectual property rights of any other entity. Each Contributor 57 | disclaims any liability to Recipient for claims brought by any other 58 | entity based on infringement of intellectual property rights or 59 | otherwise. As a condition to exercising the rights and licenses granted 60 | hereunder, each Recipient hereby assumes sole responsibility to secure 61 | any other intellectual property rights needed, if any. For example, if a 62 | third party patent license is required to allow Recipient to distribute 63 | the Program, it is Recipient's responsibility to acquire that license 64 | before distributing the Program. 65 | d) Each Contributor represents that to its knowledge it has sufficient 66 | copyright rights in its Contribution, if any, to grant the copyright 67 | license set forth in this Agreement. 68 | 69 | 3. REQUIREMENTS 70 | 71 | A Contributor may choose to distribute the Program in object code form under 72 | its own license agreement, provided that: 73 | 74 | a) it complies with the terms and conditions of this Agreement; and 75 | b) its license agreement: 76 | i) effectively disclaims on behalf of all Contributors all warranties 77 | and conditions, express and implied, including warranties or 78 | conditions of title and non-infringement, and implied warranties or 79 | conditions of merchantability and fitness for a particular purpose; 80 | ii) effectively excludes on behalf of all Contributors all liability for 81 | damages, including direct, indirect, special, incidental and 82 | consequential damages, such as lost profits; 83 | iii) states that any provisions which differ from this Agreement are 84 | offered by that Contributor alone and not by any other party; and 85 | iv) states that source code for the Program is available from such 86 | Contributor, and informs licensees how to obtain it in a reasonable 87 | manner on or through a medium customarily used for software exchange. 88 | 89 | When the Program is made available in source code form: 90 | 91 | a) it must be made available under this Agreement; and 92 | b) a copy of this Agreement must be included with each copy of the Program. 93 | Contributors may not remove or alter any copyright notices contained 94 | within the Program. 95 | 96 | Each Contributor must identify itself as the originator of its Contribution, 97 | if 98 | any, in a manner that reasonably allows subsequent Recipients to identify the 99 | originator of the Contribution. 100 | 101 | 4. COMMERCIAL DISTRIBUTION 102 | 103 | Commercial distributors of software may accept certain responsibilities with 104 | respect to end users, business partners and the like. While this license is 105 | intended to facilitate the commercial use of the Program, the Contributor who 106 | includes the Program in a commercial product offering should do so in a manner 107 | which does not create potential liability for other Contributors. Therefore, 108 | if a Contributor includes the Program in a commercial product offering, such 109 | Contributor ("Commercial Contributor") hereby agrees to defend and indemnify 110 | every other Contributor ("Indemnified Contributor") against any losses, 111 | damages and costs (collectively "Losses") arising from claims, lawsuits and 112 | other legal actions brought by a third party against the Indemnified 113 | Contributor to the extent caused by the acts or omissions of such Commercial 114 | Contributor in connection with its distribution of the Program in a commercial 115 | product offering. The obligations in this section do not apply to any claims 116 | or Losses relating to any actual or alleged intellectual property 117 | infringement. In order to qualify, an Indemnified Contributor must: 118 | a) promptly notify the Commercial Contributor in writing of such claim, and 119 | b) allow the Commercial Contributor to control, and cooperate with the 120 | Commercial Contributor in, the defense and any related settlement 121 | negotiations. The Indemnified Contributor may participate in any such claim at 122 | its own expense. 123 | 124 | For example, a Contributor might include the Program in a commercial product 125 | offering, Product X. That Contributor is then a Commercial Contributor. If 126 | that Commercial Contributor then makes performance claims, or offers 127 | warranties related to Product X, those performance claims and warranties are 128 | such Commercial Contributor's responsibility alone. Under this section, the 129 | Commercial Contributor would have to defend claims against the other 130 | Contributors related to those performance claims and warranties, and if a 131 | court requires any other Contributor to pay any damages as a result, the 132 | Commercial Contributor must pay those damages. 133 | 134 | 5. NO WARRANTY 135 | 136 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN 137 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR 138 | IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, 139 | NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each 140 | Recipient is solely responsible for determining the appropriateness of using 141 | and distributing the Program and assumes all risks associated with its 142 | exercise of rights under this Agreement , including but not limited to the 143 | risks and costs of program errors, compliance with applicable laws, damage to 144 | or loss of data, programs or equipment, and unavailability or interruption of 145 | operations. 146 | 147 | 6. DISCLAIMER OF LIABILITY 148 | 149 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY 150 | CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, 151 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION 152 | LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 153 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 154 | ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE 155 | EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY 156 | OF SUCH DAMAGES. 157 | 158 | 7. GENERAL 159 | 160 | If any provision of this Agreement is invalid or unenforceable under 161 | applicable law, it shall not affect the validity or enforceability of the 162 | remainder of the terms of this Agreement, and without further action by the 163 | parties hereto, such provision shall be reformed to the minimum extent 164 | necessary to make such provision valid and enforceable. 165 | 166 | If Recipient institutes patent litigation against any entity (including a 167 | cross-claim or counterclaim in a lawsuit) alleging that the Program itself 168 | (excluding combinations of the Program with other software or hardware) 169 | infringes such Recipient's patent(s), then such Recipient's rights granted 170 | under Section 2(b) shall terminate as of the date such litigation is filed. 171 | 172 | All Recipient's rights under this Agreement shall terminate if it fails to 173 | comply with any of the material terms or conditions of this Agreement and does 174 | not cure such failure in a reasonable period of time after becoming aware of 175 | such noncompliance. If all Recipient's rights under this Agreement terminate, 176 | Recipient agrees to cease use and distribution of the Program as soon as 177 | reasonably practicable. However, Recipient's obligations under this Agreement 178 | and any licenses granted by Recipient relating to the Program shall continue 179 | and survive. 180 | 181 | Everyone is permitted to copy and distribute copies of this Agreement, but in 182 | order to avoid inconsistency the Agreement is copyrighted and may only be 183 | modified in the following manner. The Agreement Steward reserves the right to 184 | publish new versions (including revisions) of this Agreement from time to 185 | time. No one other than the Agreement Steward has the right to modify this 186 | Agreement. The Eclipse Foundation is the initial Agreement Steward. The 187 | Eclipse Foundation may assign the responsibility to serve as the Agreement 188 | Steward to a suitable separate entity. Each new version of the Agreement will 189 | be given a distinguishing version number. The Program (including 190 | Contributions) may always be distributed subject to the version of the 191 | Agreement under which it was received. In addition, after a new version of the 192 | Agreement is published, Contributor may elect to distribute the Program 193 | (including its Contributions) under the new version. Except as expressly 194 | stated in Sections 2(a) and 2(b) above, Recipient receives no rights or 195 | licenses to the intellectual property of any Contributor under this Agreement, 196 | whether expressly, by implication, estoppel or otherwise. All rights in the 197 | Program not expressly granted under this Agreement are reserved. 198 | 199 | This Agreement is governed by the laws of the State of New York and the 200 | intellectual property laws of the United States of America. No party to this 201 | Agreement will bring a legal action under this Agreement more than one year 202 | after the cause of action arose. Each party waives its rights to a jury trial in 203 | any resulting litigation. 204 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # nrepl-doc-inject 2 | 3 | [![CircleCI](https://circleci.com/gh/tatut/nrepl-doc-inject.svg?style=svg)](https://circleci.com/gh/tatut/nrepl-doc-inject) ![PR welcome](https://img.shields.io/badge/pull%20requests-welcome-green.svg) 4 | 5 | My stab at improving Clojure docstrings. NREPL middleware to load community 6 | docstrings and inject them. 7 | 8 | # How to use 9 | 10 | * Clone this and `lein install` it (not on clojars yet) 11 | * Add dependency to project dev or user profile `[nrepl-doc-inject "0.1-SNAPSHOT"]` 12 | * Add middleware to :repl-options / :nrepl-middleware 13 | 14 | ```clojure 15 | (defproject your-project "version" 16 | ;; deps etc 17 | :profiles {:dev {:dependencies [[nrepl-doc-inject "0.1-SNAPSHOT"]]}} 18 | :repl-options {:nrepl-middleware [nrepl-doc-inject.core/doc-middleware]}) 19 | ``` 20 | 21 | ![use in cider](https://raw.githubusercontent.com/tatut/nrepl-doc-inject/master/images/reify.png) 22 | 23 | 24 | # How to contribute 25 | 26 | All namespace vars are in the same file under `docs` folder with the `.edn` suffix. 27 | 28 | Add new documentation for functions or totally new namespaces. 29 | 30 | Send PRs. 31 | -------------------------------------------------------------------------------- /docs/clojure.core.edn: -------------------------------------------------------------------------------- 1 | {"reify" 2 | {"arglists-str" "[& protocols-and-methods]" 3 | "doc" "Return a new ad hoc instance that implements given protocols. 4 | 5 | Example: 6 | ;; Define a protocol 7 | (defprotocol MakeANoise 8 | (make-a-noise [this])) 9 | 10 | ;; Create an implementing interface with reify 11 | (def impl (reify 12 | MakeANoise ;; protocol to implement 13 | (make-a-noise [_] \"hello from reify\"))) 14 | 15 | (make-a-noise impl) ;; => \"hello from reify\" 16 | 17 | You can have multiple protocols and methods in 18 | the same reify call. All methods must have this 19 | as the first argument even though there is no 20 | object associated with the instance."} 21 | } 22 | -------------------------------------------------------------------------------- /images/reify.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tatut/nrepl-doc-inject/851d0df1082b95edd45ff05afd9906acc6fc2946/images/reify.png -------------------------------------------------------------------------------- /project.clj: -------------------------------------------------------------------------------- 1 | (defproject nrepl-doc-inject "0.1-SNAPSHOT" 2 | :dependencies [[org.clojure/clojure "1.9.0-beta1"] 3 | [org.clojure/tools.nrepl "0.2.12"]]) 4 | -------------------------------------------------------------------------------- /src/nrepl_doc_inject/core.clj: -------------------------------------------------------------------------------- 1 | (ns nrepl-doc-inject.core 2 | (:require [clojure.tools.nrepl.transport :as t] 3 | [clojure.java.io :as io]) 4 | (:import (java.io FileNotFoundException))) 5 | 6 | 7 | (def loaded-namespace-docs (atom {})) 8 | 9 | (defn- load-namespace-docs! [ns-name] 10 | (let [ns-docs (try 11 | (binding [*read-eval* false] 12 | (with-open [ns-doc-in (io/reader (str "https://tatut.github.io/nrepl-doc-inject/" ns-name ".edn"))] 13 | 14 | (read-string (slurp ns-doc-in)))) 15 | (catch FileNotFoundException fnfe 16 | (println "No improved docs found for ns: " ns-name ". Maybe contribute some!") 17 | ::not-found))] 18 | (swap! loaded-namespace-docs assoc ns-name ns-docs) 19 | ns-docs)) 20 | 21 | (defn- docs-for [ns-name symbol-name] 22 | (let [ns-docs (if (contains? @loaded-namespace-docs ns-name) 23 | (get @loaded-namespace-docs ns-name) 24 | (load-namespace-docs! ns-name))] 25 | (get ns-docs symbol-name))) 26 | 27 | 28 | (defn doc-middleware [handler] 29 | (fn [msg] 30 | (if (= "info" (:op msg)) 31 | ;; Give some "arround" advice to "info" message handling 32 | (let [reply (volatile! nil)] 33 | (handler (assoc msg 34 | :transport (reify t/Transport 35 | (send [this msg] 36 | (vreset! reply msg))))) 37 | (t/send (:transport msg) 38 | (let [{:strs [ns name] :as r} @reply] 39 | ;; Merge our improved docs 40 | (merge r 41 | (when (and ns name) 42 | (docs-for ns name)))))) 43 | 44 | ;; If this is not an info request, pass it along as is 45 | (handler msg)))) 46 | 47 | (comment 48 | 49 | ;; The request 50 | {:op "info" 51 | :ns "some.project.ns" 52 | :symbol "assoc"} 53 | 54 | ;; The reply 55 | {"ns" "clojure.core" 56 | "name" "assoc" 57 | "arglists-str" "[map key val]\n[map key val & kvs]" 58 | "doc" "assoc[iate]. When applied to a map, returns a new map of the\n same (hashed/sorted) type, that contains the mapping of key(s) to\n val(s). When applied to a vector, returns a new vector that\n contains val at index. Note - index must be <= (count vector)." 59 | 60 | ;; don't care about the rest 61 | "resource" "clojure/core.clj" 62 | "static" "true" 63 | "added" "1.0" 64 | :status #{:done} 65 | "line" 181, 66 | :id "13" 67 | "column" 1 68 | "file" "jar:file:/Users/tatuta/.m2/repository/org/clojure/clojure/1.9.0-alpha19/clojure-1.9.0-alpha19.jar!/clojure/core.clj" 69 | "see-also" ("clojure.core/assoc-in" "clojure.core/dissoc" "clojure.core/merge") 70 | :session "230e0365-36f6-41c6-9471-25b8206af066"} 71 | 72 | ;; The plan: 73 | ;; - fetch EDN file for namespace, like. 74 | 75 | ) 76 | -------------------------------------------------------------------------------- /test/nrepl_doc_inject/core_test.clj: -------------------------------------------------------------------------------- 1 | (ns nrepl-doc-inject.core-test 2 | (:require [nrepl-doc-inject.core :as sut] 3 | [clojure.test :as t :refer [deftest is]] 4 | [clojure.java.io :as io])) 5 | 6 | (deftest all-files-are-valid 7 | (binding [*read-eval* false] 8 | (let [files (-> "docs" java.io.File. .listFiles seq)] 9 | (doseq [f files] 10 | (try 11 | (let [ns-docs (read-string (slurp (io/reader f)))] 12 | (is (map? ns-docs) "ns docs is a map") 13 | (is (every? string? (keys ns-docs)) "all keys are strings (symbol names)") 14 | (is (every? map? (vals ns-docs)) "all values are maps")) 15 | (catch Exception e 16 | (is false 17 | (str "Unable to read " f ": " e)))))))) 18 | --------------------------------------------------------------------------------