spacemacs

Spacemacs docs: http://develop.spacemacs.org/doc/DOCUMENTATION.html http://develop.spacemacs.org/layers/+lang/clojure/README.html https://practicalli.github.io/spacemacs/
rberger 2021-06-26T22:49:16.021700Z

How would I make it so spacemacs will not change the indention within a #_(some text) expression? I’m using that as a comment block but Spacemacs is resetting the indentation which doen’t allow me to do nested bullets.

practicalli-john 2021-06-27T18:30:22.021800Z

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

rberger 2021-06-27T19:23:33.022Z

@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 I put that in a clj or cljs file, emacs will force all the bullet items to be at the same indention:
#_(
   * 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
   )
It’s the same if I use `#_(comment ….) My emacs config is based on the practicalli spacemacs init.el though it possibly was modified at some point that might impact this. I haven’t done too many modifications though. I don’t really know how to track down what emacs feature / package might be doing this. Its not a super big deal, I ended up putting this kind of planning doc into its own markdown file. Though it would be nice to be able to make markdown blocks like that inline in the clojure files.

practicalli-john 2021-06-27T21:10:34.022200Z

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.

rberger 2021-06-27T21:31:20.022400Z

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

rberger 2021-06-27T21:34:39.022600Z

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)

practicalli-john 2021-06-28T07:50:58.022800Z

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.

rberger 2021-06-28T22:46:28.023100Z

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!