nvim-doc

name	nvim-doc
description	Write, update, and improve love2d.nvim help documentation (vimdoc) in doc/love2d.txt. Use when the user asks to write docs, update docs, generate the help file, add documentation for a function, or mentions vimdoc, help tags, or plugin documentation. Reads the plugin source code to extract API, commands, configuration, and other info from LuaCATS annotations and code structure, then writes a properly formatted doc/love2d.txt following vimdoc conventions. Do not use for general Neovim :help lookups (use nvim-help skill) or for writing README.md, CHANGELOG.md, or other non-vimdoc documentation.
allowed-tools	Bash read edit write

love2d.nvim Documentation (vimdoc)

This skill writes and updates love2d.nvim help documentation. The output is doc/love2d.txt — a plain text file that integrates with Neovim's :help system using the vimdoc format.

Vimdoc format rules

General

• Text width: 78 characters (set by modeline tw=78)
• Section separators: exactly 80 = characters
• Tags: *like-this* — lowercase, hyphens for sections
• Cross-references: |like-this|
• Indentation within sections and code blocks: 2 spaces
• File must end with: vim:tw=78:ts=8:et:ft=help:norl:

Section headers

Title in UPPERCASE left-aligned, tag right-aligned, total width 80 chars:

INTRODUCTION                                                           *love2d*
SETUP                                                           *love2d-setup*
COMMANDS                                                     *love2d-commands*

Tags

• Sections: *love2d-section-name* (lowercase, hyphens)
• Functions: *love2d.function()* (includes parens)

Function tags on a separate line ABOVE the signature, right-aligned:

                                                              *love2d.setup()*
love2d.setup({opts}) ~
  Configure the plugin.

Code blocks

Delimited by > (with filetype) and <:

>lua
  require("love2d").setup({
    path_to_love_bin = "love",
  })
<

Configuration docs

Show setup() signature, then code block with ALL default options:

>lua
  {
    path_to_love_bin = "love",   -- Path to LÖVE binary (string, default: "love")
    output = nil,                -- Output panel: nil (default), false (disable), or table (window config)
  }
<

Read the actual config module (lua/love2d/config.lua) to get real defaults.

Command docs

:Love run ~
  Run the detected LÖVE project once.

:Love watch ~
  Run with auto-restart on save (debounced 300ms).

:Love stop ~
  Stop the running LÖVE project and/or watch mode.

:Love info ~
  Show info about the current LÖVE project and job state.

:Love output ~
  Toggle the floating output panel.

Workflow

Step 1 — Read the source code

Read plugin source to extract everything needing documentation. Priority order:

1. lua/love2d/init.lua — Main module, setup() dispatcher
2. lua/love2d/config.lua — Default options
3. lua/love2d/job.lua — Job lifecycle (run/watch/stop/info)
4. lua/love2d/output.lua — Output panel
5. lua/love2d/lsp.lua — Dynamic LSP integration
6. lua/love2d/events.lua — Project detection events
7. lua/love2d/autocmd.lua — Enter/leave handlers
8. lua/love2d/health.lua — Health checks
9. lua/love2d/types.lua — LuaCATS type definitions
10. plugin/love2d.lua — :Love user command
11. compiler/love.lua — Compiler plugin (makeprg + errorformat)
12. README.md — Description (don't copy verbatim)

What to extract:

• setup() and config defaults: options, types, defaults, descriptions
• Exported functions: name, params, return type, behavior
• User commands: name, arguments, completion
• Autocmds: events listened to or fired

Step 2 — Read existing docs (if updating)

Read doc/love2d.txt fully before editing. When updating, the goal is minimal changes — only touch what's stale or missing.

• Preserve existing tag names — renaming breaks bookmarks
• Preserve section structure — never remove sections
• Preserve narrative text — explanatory paragraphs help readers
• Update stale descriptions — match current code behavior
• Add missing docs — new functions, options, commands

Step 3 — Write the help file

Follow the format rules above. Canonical section order for love2d.nvim:

1. INTRODUCTION — *love2d* — Description, table of contents
2. SETUP — *love2d-setup* — Installation and setup()
3. COMMANDS — *love2d-commands* — :Love subcommands (run, watch, stop, info, output)
4. LSP — *love2d-lsp* — LSP integration details
5. GLSL — *love2d-glsl* — Treesitter injection support
6. TROUBLESHOOTING — *love2d-troubleshooting* — Common issues (optional)

Step 4 — Validate

# Check broken references
grep -oP '\|[^|]+\|' doc/love2d.txt | tr -d '|' | sort -u | while read tag; do
  if ! grep -q "\*${tag}\*" doc/love2d.txt; then
    echo "BROKEN REFERENCE: |$tag|"
  fi
done

# Check line width
awk 'length > 78 && !/^\s*$/ { print NR": "length" chars: "$0 }' doc/love2d.txt

# Check matched code blocks
echo "Open: $(grep -c '^>' doc/love2d.txt)  Close: $(grep -c '^<' doc/love2d.txt)"