Docu

[IciaCarroBarallobre]

Hi! 👋

I’ve been exploring this framework since we use it a lot at Stritzinger, and while learning, I decided to add documentation—it helped me understand it better, and I think it could help others too.

Let me know what you think!

---

Changes

README

Updated to include a detailed description of the framework, Quick Start, How it works > Kraft HTTP Handlers and Kraft Websocket Handler and Cowboy Handlers, and Documentation.

Modules

Documented:

1. kraft.erl (main module) ✅
2. kraft_app.erl ✅
3. kraft_controller.erl ✅
4. kraft_dev.erl ✅
5. kraft_handler.erl ✅
6. kraft_instance.erl ✅
7. kraft_json.erl ✅
8. kraft_jsonrpc.erl ✅
9. kraft_rest.erl ✅
10. kraft_template.erl ✅
11. kraft_ws.erl ✅
12. kraft_ws_json.erl ✅
13. kraft_ws_jsonrpc.erl ✅
14. kraft_ws_util.erl ✅

Not documented:

1. kraft_cache.erl ❌
2. kraft_conn.erl ❌
3. kraft_content.erl ❌
4. kraft_fallback_h.erl ❌
5. kraft_file.erl ❌
6. kraft_http.erl ❌

🔧 Issues:

• Mermaid (diagram tool) is not working. It's weird cause ex_doc supports Mermaid.
• Some warnings appears about kraft_cache when generating the docs

[eproxus]

Thanks a lot! ❤️ Kraft is indeed in need of documentation since there is practically none. 😅

However, I think this PR is too large in scope and documents things in a very literal way, not really made for a user trying to use Kraft but often explaining irrelevant internal details of the implementation itself instead.

I suspect much of the documentation is AI generated (please correct me if I'm wrong) and it feels very inconsistent. Some if it just a sentence, some of it is wrong and some of it is very long detailed Markdown sections (often focusing on irrelevant implementation details). All this is very understandable since an AI doesn't understand why things are the way they are, only how things are. I'm not suggesting not to use AI at all, but this feels more in the ballpark of asking AI to "please add documentation for all modules" rather than "here's documentation for a web framework, can you review this module documentation from a Erlang beginner perspective and suggest improvements?"

I feel that this initiative would be better served by smaller, more user focused documentation PRs that can be reviewed in isolation. A good place to start would be to go through the examples and strictly document the API surface used there only, and review it from a user point of view.

What do you think?

[eproxus]

This extra line is not needed.

[eproxus]

Grammatically, this should probably be something like "This module provides...".

[eproxus]

Can you please remove any code refactoring not strictly related to adding documentation? Feel free to open another PR in case you think this is needed.

[eproxus]

The first line summary should be shorter and can avoid obvious explanations such as describing the variable names.

[eproxus]

Can you remove these delimiters? I'd like them only between "sections" (e.g. types, macros, exported functions, internal functions etc.)

[eproxus]

It was some time ago, but I believe my intention is that the user should always go through kraft:... functions, so referring to the internal function is not really helpful here.

[eproxus]

This is not true, the Kraft public API is the kraft module.

[eproxus]

This is also not really a user facing module so I wouldn't document it at all at this point to be honest.

[eproxus]

I don't get this sentence. A controllers purpose is not to just "render HTML templates". It is to process the whole request/response cycle.

[eproxus]

I don't think the user needs to know what behaviors the current module implements, as that is an implementation detail. I would prefer if the documentation is more user focused.

[IciaCarroBarallobre]

I suspect much of the documentation is AI generated (please correct me if I'm wrong) and it feels very inconsistent. Some if it just a sentence, some of it is wrong and some of it is very long detailed Markdown sections (often focusing on irrelevant implementation details). All this is very understandable since an AI doesn't understand why things are the way they are, only how things are. I'm not suggesting not to use AI at all, but this feels more in the ballpark of asking AI to "please add documentation for all modules" rather than "here's documentation for a web framework, can you review this module documentation from a Erlang beginner perspective and suggest improvements?"

You’re right that I used AI, especially to help rephrase things I initially wrote in my native language, or to refine content that I had already drafted myself. In some modules, I also used it to help me understand the structure or intent after reading through them, and also I asked it to explain parts in simpler terms.

That said, it wasn’t a case of just asking the AI to generate documentation automatically for everything. There was a manual review of all content, though of course, that doesn’t automatically mean the review was great 😅. I had about a few days to dig into everything and couldn’t afford much more time, so my main goal was to understand how Kraft works from a user’s perspective and document that learning process (including AI parts which from my point of view helps me a lot) — even if that sometimes led to exploring internal details that may not have been strictly necessary.

Just as a side note: there isn’t much long-standing public documentation on using ex_doc with Erlang, so relying on AI to generate directly proper ex_doc-style docs for Erlang isn’t very reliable.

Thank you for your feedback — I really appreciate you taking the time to read this PR.

---

I feel that this initiative would be better served by smaller, more user focused documentation PRs that can be reviewed in isolation. A good place to start would be to go through the examples and strictly document the API surface used there only, and review it from a user point of view. What do you think?

Sure, that sounds great and I think that would be less chaotic 😊

Would you suggest starting with:

• Rewriting the README I’m not entirely sure what to keep or cut — maybe add a “dev mode” section, and simplify the current “How it works” by just listing the main handler modules for users to explore.
• Documenting the examples/ folder
• Clarifying the “API surface” scope: Should I focus only on public-facing module documentation and skip low-level/internal functions?

---

🔍 Based on your comments, here’s what I think should be kept, but cleaned up and better documented per file:

• kraft_instance.erl – Seems fine as is for me.
• kraft_handler.erl – I’d remove the “Handler Types” section and just reference it in “See also.” Also planning to remove “Response Types” and “Error Handling.”
• kraft_rest.erl – Might remove the “Usage” section.
• kraft_template.erl – Planning to remove “Features” and “Template Location” and include that info in the main description instead.
• kraft_ws.erl – I’d keep the “Callbacks” section and, if needed, explain frame types within individual function docs.
• kraft_ws_json.erl – Remove “Usage” and “Error Handling.”
• kraft_ws_jsonrpc.erl – Remove the “Usage,” “Error Handling,” and “JSON Conversion” sections. Reduce the “Batch Processing” section. Also remove the example in the message callback.
• kraft_controller.erl – Clean up PR-style comments, remove “Usage,” and integrate the state/data explanation into the “How it works” section.
• kraft_jsonrpc.erl – I think it’s important to explain batching, single requests, input/output formats, and link to the JSON-RPC spec — though maybe this content could live in kraft_ws_jsonrpc.erl instead? idk

🗑 Candidate for removal:

• kraft_ws_util.erl, kraft_app.erl
• Documentation for the kraft_json.erl and kraft_jsonrpc.erl module

---

I’d really like to keep the “See also” sections — I find them super helpful when navigating and connecting pieces together.

Let me know what you’d prioritize, and I’m happy to start iterating based on that. 😊

[IciaCarroBarallobre]

Would it make sense to agree on a format to keep module documentation consistent — both in function docs and module-lvl docs? I think I tried to make it consistent, but didn’t quite manage it.

Example format for module docs:

# Module name
<Brief description>

## Usage
<Code example or usage notes> 

## See also
<Related modules>: A brief explanation of each

Idk if you prefer to remove Usage

No idea what to use for functions without being really verbose. Elixir function docs are like:

%% Short, descriptive summary of what the function does.
%%
%% ## Parameters
%% - `Param1` – What it represents.
%% - `Param2` – Optional, if applicable. Description here.
%%
%% ## Returns
%% - Description of the return value. If multiple cases, explain them.
%%
%% ## Examples
%% ```
%% kraft_handler:handle(#{method => <<"ping">>}, State).
%% %=> {reply, #{result => <<"pong">>}, State}
%% ```

[IciaCarroBarallobre]

Anyway, first of all, I'm going to fix all the comments that you did :) to have a better starting point