Documentation improvement suggestions

greglook / cljstyle

A tool for formatting Clojure code

Eclipse Public License 1.0

293 stars 39 forks source link

Documentation improvement suggestions #37

Open bbatsov opened 4 years ago

bbatsov commented 4 years ago

Hey there!

I just came across the project (which looks pretty cool, btw) and I have a couple of small suggestions to improve the docs:

Might be a good idea to publish the docs folder to a service like ReadTheDocs. This requires almost no work from you, just adding a configuration file for the service. I didn't notice the doc files originally and I thought the README was a bit short on details.
I think it'd be great if there's some rationale for rewriting cljfmt (which I've been using for a while), as it's not very clear what exactly are the advantages of cljstyle
I think it's a good idea to indicate where are the defaults derived from. I'm hoping that's the community style guide, but I couldn't find any indication of this in the docs.

Thanks for the great project! 🙇

greglook commented 4 years ago

Hi bbatsov, thanks! Publishing would be neat - there are links from the relevant README sections, but maybe they're not discoverable enough.

I'll put the rationale in a doc, but there were a couple of things I wanted when I first forked cljfmt:

A better way to specify configuration local to certain bits of code.
Namespace-matched and pattern-matched indent rules.
Enforced line-breaks for some function, var, and type forms.
Canonical ns rewriting.
A stand-alone binary tool.

The defaults are indeed mostly from the community style guide, with the main exception being the default two-space indent. That's configurable back to one space for those who want it, but it never really made sense to me.

bbatsov commented 4 years ago

Sounds good to me!

The defaults are indeed mostly from the community style guide, with the main exception being the default two-space indent. That's configurable back to one space for those who want it, but it never really made sense to me.

I know this is probably the most controversial topic when it comes to code layout, but I was doing Lisp(s) way before Clojure, so I got used to this a long time ago. :-) As a bonus - it makes it really easy to spot some macro that operates on a body of code and function calls with multi-line arguments. Anyways, I understand your point.