# Documentation

is generating docs based on the tree sitter syntax tree. TJ wrote a grammar that includes the documentation in this syntax tree so we can do take this function header documentation and transform it into vim documentation. All documentation will be exported that is part of the returning module. So example:

local m = {}

--- Test Header
--@return 1: Returns always 1
function m.a()
  return 1
end

return m

Something like this.
What is missing?

The docgen has some problems on which people can work. This would happen in https://github.com/tjdevries/tree-sitter-lua and documentation of some modules here.
I would suggest we are documenting lua/telescope/builtin/init.lua rather than the files itself. We can use that init.lua file as "header" file, so we are not cluttering the other files.
How to do it:


## Auto-updates from CI

The easy way would be after this PR is merged

    write some docs
    commit and push
    wait a minute until the CI generates a new commit with the changes
    Look at this commit and the changes
    And apply new changes with git commit --amend and git push --force to remove that github ci commit again.
    Repeat until done

## Generate on your local machine

The other option would be setting up https://github.com/tjdevries/tree-sitter-lua

    Install Treesitter, either with package manager or with github release
    Install plugin as usual
    cd to plugin
    mkdir -p build parser Sadly does doesn't exist laughing
    make build_parser
    ln -s ../build/parser.so parser/lua.so We need the so in parser/ so it gets picked up by neovim. Either copy or symbolic link
    Make sure that nvim-treesitter lua parser is not installed and also delete the lua queries in that repository. queries/lua/*. If you are not doing that you will have a bad time
    cd into this project
    Write doc
    Run make docgen
    Repeat last two steps