compile / test / format gleam code markdown code blocks in module and function comments

[inoas]

• Blocks of gleam code with triple markdown ticks in docblocks of modules and functions could be automatically formatted using the same rules as those for regular gleam code, if possible.
  • Fancier idea with probably even lower priority: Code in those docblocks could also be put into magic main functions (minus import statements) and compiled to see if it would compile.
    • Another backticked gleam code syntax could be introduced that stops compliation such as [triple-tick]gleam-no-compile
    • Based on that we could add @doctest or similar attribute to run those when gleam test is executed, again putting them into virtual test functions and respecting imports
• Another few languages could be supported for formatting, such as Erlang, Elixir, JavaScript, TypeScript, XML, HTML, CSS, JSON, TOML, SQL.

Tagging @giacomocavalieri as requested

---

Edit: I think doctests are great (for pure functions) as they can reside with function docs and function typespecs all in one place for best comprehension.

[inoas]

For an example of doctests in Elixir, see https://hexdocs.pm/elixir/docs-tests-and-with.html#doctests

[giacomocavalieri]

I think formatting gleam code in a doc comment's code block could be nice. I like the idea of having a nice and consistent look across all examples.
As for the formatting other languages, I don't think that will give us much value: we would have to either implement our own custom formatters or depend on external tools. That seems like a lot of work for very little gain. Focusing just on Gleam code sounds great to me!

[inoas]

For running the compiler and-or doctests we could do the following, using forward ticks here for demo only.

1. extends the triple-tick markdown syntax to take an argument:
   • ´´´gleam compiled-markdown-code-block, which compiles the given code but does not run it as part of the test suite, the flag could be different than compiled, just an idea.
   • ´´´gleam doctest-markdown-code-block, which compiles the given code snipplet and runs it as part of the test suite as if it was a pub fn *_test in the test dir.
2. ´´´gleam-, ´´´gleam run- and ´´´gleam test-blocks would all be autoformatted as per almost normal rules but obviously indended by triple or quadruple slashes.
3. to make this possible:
   • create a virtual module of the current module where the current doctest gleam code snipplet is in a virtual function
   • copy all the imports from the doctest gleam snipplet into that virtual module
   • thus functions in the current module, private or public, are accessible in unqualified fashion, but modules, functions, types, constructors in other modules must be imported.
   • Edit: > value would be the expected value from the doctest
   • Edit: >stdout value would be the expected stdout output
   • Edit: >stderr value would be the expected stdout output
   • Edit: >, >stdout and >stderr appear multiple times
   • Edit: >stdout and >stderr and wrap the code before as if it was a callback that captured the stdout/stderr replacing another callback for stderr xor stdout

[lpil]

If we generated these extra modules per code block how would the program run them in their tests?

How would imports work?

[inoas]

How would imports work?

I have explained that above already, was there any issue with the proposal?

[inoas]

Testing if github ignores flag of flagged docblock (´´´gleam doctest preamble):

import gleam/int

{1 + 2} |> int.divide(2)
> 1

[inoas]

If we generated these extra modules per code block how would the program run them in their tests?

How would imports work?

• They could be placed in test/generated.
• They could be updated by running gleam build-doctests or similar

[lpil]

Placing them in test/generated wouldn't be enough for any test runner to run them unfortunately.

[inoas]

I have edited my comment above to include how the expected function return value, stdout or stderr could be tested/captured.

[inoas]

I wonder if the testing part could for demo purposes done as a community plugin first. It would not happen at lsp/save-time and would not report back syntax errors or doctest failures right away but it could be a good POC that is useful on its own and stdlib could even be upgraded to yse it, if it is good enough?

[inoas]

If doctests make it into the gleam itself, the generated erlang could be placed as erlang doctests:

https://www.erlang.org/eeps/eep-0059#doctests

This improves documentation for the beam eco-system and improves gleam's appeal to use it as for beam eco system libraries.