What should our documenting standard be like?

[DrKJeff16]

Description

I am concerned about how we will do our field descriptions, so I'd like every maintainer / collaborator that's interested
to join in on this discussion (@craigmac && @TheLeoP , I'm pinging you (sorry) if you have any feedback).

My Suggested Standard

THIS IS NOT THE LAW.
I DON'T WANT TO ENFORCE MY PERSONAL STANDARDS, I'M SIMPLY EXPLAINING HOW I'VE
DONE IT SO FAR

---

---@ comments should go with three dashes, while any other description should go with only two dashes

Find and Replace operations (:%s, Vim users will get it) might benefit from this by differentiating and avoiding mistakes.

Also it makes description comments much easier to spot for manual searching.

No inline ---@field descriptions

This is because LuaLS supports Markdown comments¹.
Having inline comments not only makes the comments harder to navigate through,
it also limits what we can write (say, lists/tables/sections/etc.)

-- I disagree with the following:
---@class Foo
---@field bar? fun(...:any) This does bar

-- Instead
---@class Bar
-- This does `foo`
---@field foo? fun(...: any)

In descriptions, any identifier, type and/or value should be enclosed like in Markdown

This is because it lets users spot important info much faster when hovering.

• leader_key, 1.0, "FOO" - Not suggested
• leader_key, 1.0, "FOO" - Suggested

---

Footnotes

1. Annotation Formatting ↩

[craigmac]

I'll give my opinions on your suggested standards first:

---@ comments should go with three dashes, while any other description should go with only two dashes

I disagree with this one, it should be 3-dash all the time, I checked several repos on LuaCATS and none
of them use 3-dash/2-dash hybrid, it's always 3-dashes for everything. I don't your arguments for otherwise
are convincing because they are not problems that we have. Let's stick to the
defacto standard, and only deviate if we really have good reasons to.

No inline ---@field descriptions

I'm fine with this one. My research suggests this is mostly how it's done.
I also think many @alias should be done this way too.

In descriptions, any identifier, type and/or value should be enclosed like in Markdown

Agree.

Given there's no easy quick-win like a 'fire-and-forget' formatter
that everyone uses for these definition files, I'd suggest we just
follow the herd and established practices in the wild. De-facto
standards body seems to me to be the
LuaCATS organization on github, but I could
be convinced otherwise!

The lua-language-server repo has a tools folder, which has some scripts
that generate both the love2d and love definition files. So I'd consider them
to be as close to the standard as we can get. See build-3rd-meta.lua.

On the formatting note, I think we should just use whatever stylua defaults are and be done with it 🤷

[DrKJeff16]

No inline ---@field descriptions

I'm fine with this one. My research suggests this is mostly how it's done. I also think many @alias should be done this way too.

I am yet unsure about the behaviour of aliases with descriptions. Take, for instance, lua/types/enum/copy-mode-assignment.lua.

Setting an arbitrary variable with CopyModeAssignment alias shows this on hover

---

---@ comments should go with three dashes, while any other description should go with only two dashes

I disagree with this one, it should be 3-dash all the time, I checked several repos on LuaCATS and none of them use 3-dash/2-dash hybrid, it's always 3-dashes for everything. I don't your arguments for otherwise are convincing because they are not problems that we have. Let's stick to the defacto standard, and only deviate if we really have good reasons to.

Very well then. We should then rework the existing ones and apply this for the future ones.

If using Bash, I have this script that must be called while in the root of the repo (USAGE INCLUDED)

#!/usr/bin/env bash

# Print to `STDERR`, separate each arg with newline
error() {
    local TXT=("$@")
    printf "%s\n" "${TXT[@]}" >&2
    return 0
}

# Check whether a console command (or multiple) exists
# Returns 0 if all commands are found
# Returns 1 if at least one command is not found
# Returns 127 if no arguments were given
_cmd() {
    [[ $# -eq 0 ]] && return 127

    local EC=0

    while [[ $# -gt 0 ]]; do
        if ! command -v "$1" &> /dev/null; then
            EC=1
            break
        fi

        shift
    done

    return "$EC"
}

# Terminate the script, optionally set the exit code and abort message
die() {
    local EC=1

    if [[ $# -ge 1 ]] && [[ $1 =~ ^(0|-?[1-9][0-9]*)$ ]]; then
        EC=$1
        shift
    fi

    if [[ $# -ge 1 ]]; then
        local TXT=("$@")
        if [[ $EC -eq 0 ]]; then
            printf "%s\n" "${TXT[@]}"
        else
            error "${TXT[@]}"
        fi
    fi

    exit "$EC"
}

! _cmd 'find' && die 127 "\`find\` is not in PATH."

[[ $# -eq 0 ]] && die 127 "No arguments were given. Aborting"

EC=0

while [[ $# -gt 0 ]]; do
    if ! [[ "$1" =~ ^s/.+/.*/g?.*$ ]] ; then
        error "Pattern \`$1\` not valid. Skipping..."
        EC=1
        shift
        continue
    fi

    REGEX="$1"

    printf "\n%s\n" "Applying regex ${REGEX}:"
    for F in $(find . -type f -regex '.*\.lua$' | cut -d '/' -f2-); do
        echo -e "    ==> ${F}"
        if ! sed -i "${REGEX}" "$F"; then
            error "Unable to replace contents of file \`$F\`. Skipping file"
            EC=1
            continue
        fi
    done

    shift
done

die "$EC"

USAGE:

$ ./script_name 's/^--\s/---/g'

---

On the formatting note, I think we should just use whatever stylua defaults are and be done with it 🤷

StyLua barely benefits us since they're mostly annotations. It is there for our workflow to avoid anyone pushing badly formatted files.

If we were to transition to Definition Files, only some .stylua.toml fields matter, that I can think of:

line_endings = "Unix"
collapse_simple_statement = "Always"

Tangent: welp, gotta change Lua version in our .stylua.toml file :p

[craigmac]

weird, ok will reupload them again later

[DrKJeff16]

Update

@craigmac
I've created a PR regarding the --- comments. Also, I think you mistakenly
left a blank line (fixed now)

#51

[DrKJeff16]

weird, ok will reupload them again later

This is how it looks for me:

---

---

[craigmac]

reuploaded them

[DrKJeff16]

@craigmac are you using nvim-lspconfig? I know it's outdated for >v0.11.0 but it still adds hooks to the LSP core.

ADDENDUM: The colorscheme might be a factor, aswell...

[DrKJeff16]

Addendum

@craigmac
The <> tags shown in https://github.com/LuaCATS/lovr/blob/main/library/filesystem.lua
don't render in my case for Neovim LSP (tried to, failed)

Also, if you want to discuss about this in more detail and more fluidly, you can send me an email to get in touch, if you're so inclined.

[craigmac]

Picture is up, added further notes.

[DrKJeff16]

@craigmac Issue: After doing the --- update, the config.quick_select_alphabet
field does not render anymore. It's a markdown table.

---

Only solution is to fall back to -- comments:

[craigmac]

is that even valid markdown? can you check with a validator, minus the leading triple dashes. maybe it's because column headers for the table are missing? nvim logic might need to be tweaked if this is valid markdown, looks like it's interpreting part of the table as a thematic break.

[DrKJeff16]

Issue is --- comments before a | character, no matter if a space is between,
make the renderer think it behaves like multiline type assignment:

---@alias Foo
---|"Bar"

Also, I forgot the headline lmao (it still behaves weirdly though):

qwerty	"asdfqwerzxcvjklmiuopghtybn" (default)
qwertz	"asdfqweryxcvjkluiopmghtzbn"
azerty	"qsdfazerwxcvjklmuiopghtybn"
dvorak	"aoeuqjkxpyhtnsgcrlmwvzfidb"
colemak	"arstqwfpzxcvneioluymdhgjbk"

[craigmac]

Hmm, could you raise an issue with neovim about this? I believe it would be MariaSolOs who
implemented the logic for the current markdown rendering, looks like this regex might
be related: https://github.com/neovim/neovim/blob/a9a4c271b13fffba2a21567c86b0f40ae4c180a1/runtime/lua/vim/lsp/util.lua#L1102