Fork me on GitHub

It's my first time using Marginalia. I've always been very skeptical of "literate programming" but I was recently looking for a "better documentation generator" for Clojure, for internal use, rather than for documenting an API, and it looked interesting.


I'm building out a completely new product at work so being able to write down a narrative of how I want it all to work, and then turn pieces of it into well-documented code appeals to me. And so far, it's working well. As I've written out the narratives and started adding code, I've found several edge cases that I probably wouldn't have thought about with just the code (or even with just test cases).


That's interesting, are you writing doc strings only or actual prose?


A combination of both. Actual prose in between top-level forms can either be separate blocks of documentation or added to the docstring of the following block (depending on whether you have a comment immediately prior to the form or not).


The main thing I wanted that it did not do was to handle inline comments in the code, turning them into paragraphs of prose after the docstring. I submitted a PR for that.


Yeah that is a nice thing, comment is nice to read because it contains usage examples.


(comment ...) forms will stay in code (on the right), but ;; inline comments will be included in the documentation (on the left) as well as staying in the code.


I need to add some more stuff to the Marginalia test code before I mess with it too much more. It might be a nice option, when lifting inline comments into documentation to also remove them from the code. I'll have to think about that.


oh ok so I should use ;; for my use case...`(comment)` feels better because it provides better separation to me I guess (and emacs grays it out)


In ProtoREPL, it won't eval code in ;; comments but it will eval code in (comment ...) so I use them for different things.


oh really, if I eval the (comment) format it should not do anything right? I usually use C-c C-e for evaluating espressions within comment though..


oh ok cool sorry I misread


How do I include java modules in boot? Specifically javax.xml.bind


@arijun Maybe BOOT_JVM_OPTIONS=--add-modules java.xml.bind


getting ready to learn boot! Is there an analog to lein new in boot-speak?


@aaelony boot -d boot/new new -t {template} -n {projectname}


(the nice thing with Boot is that you can specifies dependencies on the command line to get access to libraries and tasks without needing them in a project struct... I often run boot -d some/thing repl which I want to just play with a new library via the REPL!)


Boot New also has "generator" functionality that can add stuff to an existing project. It hasn't been fleshed out very far yet but I can imagine generators for "new Ring handler" and so on at some point.


Oh, and Boot New will render both Leiningen and Boot templates.


There are lots of Leiningen templates because it's been around for ages but the number of Boot templates is steadily growing


Thanks, Sean, that's great. I guess the first step is to try to take an existing project and try to convert it


I wrote boot-new so ping me if you have any questions!