Document Builtins by Language

[Geraint]

The BUILTINS.md file is very long.

It's currently split into sections for each of the groups of sources (code action, diagnostics, formatting, hover and completion), and then alphabetically within each group.

This arrangement makes it quite easy for contributors to make errors - I notice, for example, that the documentation for php is under the formatting group, when it should be under diagnostics.

I appreciate that its reference information, but it can be a little tricky to find things - I have to search the document, rather than just browsing it, because there's too much information that is not relevant to my personal requirements.

I'm in the process of migrating from Ale to null-ls. Ale documents things by (programming) language, and this arrangement seems to be better in my personal opinion.

For example, when I want to see what ALE linters I can use with PHP, I can just browse the relatively uncluttered ale-php.txt.

So, I suggest that null-ls should also document things by language, making new files with (perhaps) names like

• BUILTINS-lua.md
• BUILTINS-php.md

... etc.

I appreciate that some builtins support multiple file types, and the proposed change would mean be duplication.

The ALE Typescript documentation points the user at the ALE JavaScript documentation in situations like this:

===============================================================================
prettier                                              *ale-typescript-prettier*

See |ale-javascript-prettier| for information about the available options.

null-ls could do the same thing.

[jose-elias-alvarez]

As far as accuracy goes (I agree it's a big issue), in #552 we discussed embedding the documentation metadata directly into the built-in files so that (among other uses) we can automatically generate documentation. I'm not personally a fan of the ALE approach–I prefer a single document I can search in–but if there's demand, it shouldn't be too hard to tweak a basic document generation script to generate language-specific files.

[Geraint]

I didn't see that issue before - thanks for pointing it out.

Including the metadata in the code itself does sound like it would improve accuracy and be flexible.

Might an existing tool like LDoc be adequate?

[jose-elias-alvarez]

Interesting, I hadn't heard of LDoc but definitely want to look into it. If it doesn't add significant complexity, I definitely prefer to use comments for metadata (vs. directly embedding it into the built-in table itself). Thanks for the link!

[Geraint]

You're welcome.

I've used tools like phpDocumentor before, and have seen similar tools for .Net and Java, so I figured there was likely a Lua equivalent.

The nice thing with phpDocumentor is that IDE's and static analysis tools understand the annotations too, so you get benefits over and above auto-generating documentation.

I don't know enough about the Lua ecosystem to know if LDoc is the defacto standard, but the LuaDoc README is saying to use LDoc instead.