Clojurians Log v2

Sorry, I don't understand the question or what nested bullets are in Clojure, do you have a specific example?

@jr0cket Lets say I wanted to have something like

#_(
* If foo room/token info does not yet exist for this event
   * Create the foo room for the event
     * `name`: Ether set it as a kebab-case version of the display-name or empty
       * If empty, foo will set a unique name
     * `privacy`: Optional "private" | "public" defaults to public
)

#_(
   * If foo room/token info does not yet exist for this event
   * Create the foo room for the event
   * `name`: Ether set it as a kebab-case version of the display-name or empty
   * If empty, foo will set a unique name
   * `privacy`: Optional "private" | "public" defaults to public
   )

As it's not Clojure, I would write this text as line comments using ;; A (comment ) block could be used to contain this text as line comments, interspersed with actual Clojure code on its own lines, if that aids with implementation.

Yeah, I hate that (Code blocks with each line requiring semi-colons) Have the added complication that I’m trying to document re-frame handlers which can’t use docstrings ;-(

Like I said, not a big deal, but this is an area where IMHO, clojure falls down a bit. There should be less friction to document things. (Note: I love clojure[script], this is a nit)

I'm afraid I don't share the same view. I find Clojure is very easy to document and add live documentation with rich (comment ,,,) blocks, more so that most languages I've worked with. And Spacemacs has gcc key binding to convert a line to a line comment and gc to convert a region to a line comment. If re-frame handlers cannot have doc-strings, then that is a negative aspect of the re-frame design and I would question why they cannot have doc strings. There are always line comments as a fallback. To me, this is separate from documenting Clojure itself. I aim to write code that is highly readable, which is usually quite easy in Clojure. I find doc strings are an essential part of the code design and should elaborate on the reason for this particular function to exist. This may be complemented by a rich comment block that shows examples of how to work with a particular piece of code. Then you have the ubiquitous line comment for anything else (namespace headers, logical separation of code sections - also helps with refactoring) I also find having a separate design journal namespace invaluable for capturing the essential design decisions that are otherwise so easily lost.

One issue is that the commnets / comment blocks don’t show up in codox views. And I’m at a loss as to what to do with re-frame events/subscriptions which are declared with something other than fn/`defn` and thus can’t have docstrings or show up in codox views. Someone suggested a macro but that seems like its going to end up getting complicated. I kind of wish metadata was universal (could be applied to any clojure element) and then be able to have more structural docstrings. Like put the argument descriptions with each argument as a meta tag. Or still create a docstring for the keyword names and arguments of the re-frame events/subscription definitions that could be interpreted by codox or other similar tools… Anyway, this is probably not the right forum for this discussion. Appreciate your help and insights!