Call to library authors: define "Nutrition facts" for your meta-programming

[josevalim]

@hubertlepicki

The documentation is static, and has to be maintained, the language server is dynamic and can generate an actual report, that would take into consideration options pased to the “use” macro, to give me a precise overview of what actually happened to my code when I used it.

Honestly, we need both. Telling a newcomer that they can “see expanded macro” to figure what use does it not necessarily the best experience. We could introspect this automatically but it is hard to separate what is public (we set this attribute that directly impacts you or is public API) vs private (we generated this function/attribute that you should never care about). But the expanded macro feature is great for experienced devs.

@Qqwy

@josevalim This is the first time I’ve seen the {: .info} syntax. I love how it looks, but starting at which version does ExDoc support this?

Check ExDoc readme (we recently added tabsets too). In there since v0.28.x, more than a year ago.

[Eiji]

@josevalim

v0.28.x,

To be precise as of changelog it was v0.28.1.

v0.28.1 (2022-02-20)

• Enhancements

  • Add support for admonition text blocks
  • Improve accessibility for light and dark themes

• Bug fixes

  • Ensure that mix docs --open works on Windows
  • Ensure search tokenizer also splits on underscore
  • Fix false warnings about missing types when running ExDoc in escript mode
  • Don’t navigate when clicking the current page

@Qqwy You can find more info in documentation of Admonition blocks.

[zachdaniel]

The nutrition facts for use Ash.Resource would be quite a meal