Fork me on GitHub
#boot
<
2017-11-10
>
seancorfield02:11:39

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.

seancorfield02:11:24

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).

richiardiandrea04:11:46

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

seancorfield05:11:40

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).

seancorfield05:11:24

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.

richiardiandrea06:11:52

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

seancorfield17:11:16

(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.

seancorfield17:11:44

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.

richiardiandrea21:11:47

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)

seancorfield21:11:46

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

richiardiandrea22:11:04

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..

richiardiandrea02:11:52

oh ok cool sorry I misread

arijun11:11:44

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

juhoteperi11:11:21

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

aaelony23:11:31

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

seancorfield23:11:33

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

seancorfield23:11:27

(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!)

seancorfield23:11:43

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.

seancorfield23:11:04

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

seancorfield23:11:08

There are lots of Leiningen templates because it's been around for ages https://clojars.org/search?q=lein-template but the number of Boot templates is steadily growing https://clojars.org/search?q=boot-template

aaelony23:11:24

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

seancorfield23:11:09

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