NNashwin nnashwin

How Clojure's documentation can leapfrog other languages

Summary

I made a documentation generator that cashes in on Clojure's dynamism. See the play-cljs docs (a ClojureScript game library) for an example of its output.

The Problem

Like many of you, I've often wondered what my final regret will be on my deathbed. My best guess came to me in a dream recently. I was walking across the charred earth of an apocalyptic future world, maneuvering around the remains of the less fortunate. I was startled to find a young girl, barely holding onto her life. She murmured something to me. I asked her to repeat it, and she said more loudly: "I...wish your Clojure projects didn't have such crappy documentation."

My answer to: https://www.reddit.com/r/Clojure/comments/pcwypb/us_engineers_love_to_say_the_right_tool_for_the/ which asked to know when and at what is Clojure "the right tool for the job"?

My take is that in general, the right tool for the job actually doesn't matter that much when it comes to programming language.

There are only a few cases where the options of tools that can do a sufficiently good job at the task become limited.

That's why they are called: General-purpose programming languages, because they can be used generally for most use cases without issues.

Let's look at some of the dimensions that make a difference and what I think of Clojure for them:

	package main

	// The string values of the 2 classes
	// They can be "positive" >< "negative" as in this example
	// They can also be "ham" >< "spam", i.e.
	const (
	positive = "positive"
	negative = "negative"
	)

	prog :=xnixperms

	debug ?=

	$(info debug is $(debug))

	ifdef debug
	release :=
	target :=debug
	extension :=debug

	import { useState, useCallback, useRef } from "react";

	// Usage
	function App() {
	const [hoverRef, isHovered] = useHover();

	return (
	<div ref={hoverRef}>
	{isHovered ? '😁' : '☹️'}
	</div>