How to generate documentation for Crystal's compiler?

Are there any recommendations?

What kind of documentation are you thinking of? Like manually building the API docs you can see at Crystal 1.11.0-dev or?

1 Like


There’s a make target for it:

make docs

I just tried it. But it doesn’t generate documentation for the classes that make up the compiler.
Is there an option to generate documentation for the compiler?

No, the compiler docs are considered internal/private so there are no public API docs for them. There still may be comments on things, but there isn’t a rendered view of them.

Compiler internals · crystal-lang/crystal Wiki · GitHub may be worth a read as well, but not sure how up to date it is.

1 Like

I looked at the Makefile. It runs

.PHONY: docs
docs: ## Generate standard library documentation
        $(call check_llvm_config)
        ./bin/crystal docs src/ $(DOCS_OPTIONS) --project-name=Crystal --project-version=$(CRYSTAL_VERSION) --source-refname=$(CRYSTAL_CONFIG_BUILD_COMMIT)

I edited and it generated the documentation for Crystal’s compiler.

diff --git a/src/ b/src/
index 661163677..1f7cbb04b 100644
--- a/src/
+++ b/src/
@@ -5,6 +5,7 @@
 require "./annotations"
 require "./big"
 require "./compiler/crystal/macros"
+require "./compiler/"
 require "./compress/**"
 require "./crypto/**"
 require "./crystal/syntax_highlighter/*"

I guess that’s the solution for now.

You can add the compiler entry point to the docs command via Makefile argument:

make docs DOCS_OPTIONS=src/compiler/

This generates the combined API docs for the compiler and stdlib.