What is the difference between ; and ;; in Clojure code comments?

Question

What is the difference between ; and ;; when starting a comment in Clojure? I see that my text editor colours them differently, so I'm assuming there is notionally some difference.

I also see that Marginalia treats them differently:

; Stripped entirely ;; Appears in text section of marginalia (defn foobar []    ; Appears in code section of marginalia output    ;; Again, appears in code section of marginalia output    6) 

Answer 1

There is no difference as far as the interpreter is concerned. Think of ; ;; ;;; and ;;;; as different heading levels.

Here is my personal use convention:

;;;; Top-of-file level comments, such as a description of the whole file/module/namespace  ;;; Documentation for major code sections (i.e. groups of functions) within the file.  ;; Documentation for single functions that extends beyond the doc string (e.g. an explanation of the algorithm within the function)  ; In-line comments possibly on a single line, and possibly tailing a line of code 

Answer 2

Check out the official description of the meaning of ; vs ;; in elisp: since the Clojure indenter is basically the same, it will treat them similarly. Basically, use ; if you are writing a long sentence/description "in the margins" that will span multiple lines but should be considered a single entity. Their example is:

(setq base-version-list                 ; there was a base       (assoc (substring fn 0 start-vn)  ; version to which              file-version-assoc-list))  ; this looks like                                         ; a subversion 

The indenter will make sure those stay lined up next to each other. If, instead, you want to make several unrelated single-line comments next to each other, use ;;.

(let [x 99 ;; as per ticket #425       y "test"] ;; remember to test this   (str x y)) ;; TODO actually write this function