Very cool

Not in the sense thatbI’d ever use it, but in the sence that it makes me want to use it, even though I probably shouldn’t…

I’ve written a similar thing, which I’ve named Doktor. It’s like you regular old Doc, but younger, cooler and more radiKal. Because it had a K. It allows you to write this:

defmodule My.Module do
  use Doktor, "dok/docstrings_for_my_module.md"
  @moduledok "My.Module"

  @dok "hey/0"
  def hey(), do: "Hey!"

  @dok "hello/1"
  def hello(name), do: "Hello #{name}!"
end

Basically, Doktor takes up an Markdown (MD - ) file annotated in a special way and, extracts docstrings from that file and documents the functions with those docstrings. This kan help deKlutter your modules, because it moves the doKstrings somewhere else. I’m still not sure on how useful this is (or whether it is even a good thing at all), but it’s just so KOOL xD

The way it works is by overwriting the @ operator inside the use macro so that it treats the @dok, @moduledok and @typedok` In a special way. Although it’s completely different, it reminded me of this somehow.

haha you got me, I’m always looking at what things I’m able to do with the Elixir syntax, and yeah, the formatter doesnt like it that much, maybe in could be treated just like do and allow a new line after it.

Hey Doktor looks awesome, I’ve been using just @moduledoc File.read!("README.md") but your tool looks nice. One thing I’ve noticed while running tests from an .md file is, I need to modify the .ex file importing it for the new tests to take place, otherwise it’s already compiled with no changes. How you’d handle that in doktor.

I like this trick of linking with in here! I wonder how the formatter formats that though, hmm…

Testing…

iex(1)> Code.format_string!("""
...(1)>    deco {Deco.around(is_authorized)} in
...(1)>    def create(conn, params) do
...(1)>      ...
...(1)>    end
...(1)> """) |> IO.puts()
deco {Deco.around(is_authorized)} in def(create(conn, params)) do
  ...
end

Aww that’s sad, and no way to fix the formatter for this either currently…

You can use this module attribute: https://hexdocs.pm/elixir/Module.html#module-external_resource

In the case of Doktor, because I’m doing funny things in the use macro (like overwriting @/1) I can add the attribute automatically (I’m not doing it yet, but I can add it), but you’ll have to add it manually with your approach. Mix will recompile your module each time the external file changes. People should always use this attribute when their modules depend on an external file.

In your case, it’s just a question of:

@external_resource "README.md"
@moduledoc File.read!("README.md")

But are you serious about Doktor? Would you use this? xD

I’m not sure I like overwriting the @/1 operator that much, even though it looks nice, because it reuses the familiar pattern of documenting a function or a module. I haven’t released it now because the current implementation is very inefficient. I parse the file everytime I want to document a function. I should start an Agent when the module is compiled, gather all documentation snippets into the agent, have my modified @/1 macro retrieve the docstrings from the agent and kill it after compilation. Compilation of a module is probably done by the same process (I haven’t checked), so this will not be a bottleneck.

Maybe Docktor should use normal functions like

moduledok "My.Module"

dok "hey/1"
def hey(name), do: "hey #{name}"

But last time I tried this there were some small problems of things not being defined before other things. I have to try again. And I do like writing @dok…

I’ve released Doktor (not public on hex yet, or maybe ever): Doktor: extract docs from external files

It now has a much better design. It still doesn’t use the @external_resource thing. I should add it…