renderLuaLsAnnotations function

String renderLuaLsAnnotations(List<Library> libraries, { String packageName = 'lualike', String? packageVersion, })

Renders LuaLS-compatible annotation stubs for the documented libraries.

The output is valid Lua source intended to be indexed by LuaLS as a definition file. It uses ---@meta, table declarations, ---@param, and ---@return annotations so existing Lua language tooling can provide completion, hover text, and signature help without LuaLike owning an LSP.

Implementation

String renderLuaLsAnnotations(
  List<Library> libraries, {
  String packageName = 'lualike',
  String? packageVersion,
}) {
  final buf = StringBuffer()
    ..writeln('---@meta _')
    ..writeln('---Generated LuaLS annotations for $packageName.')
    ..writeln('---Do not execute this file; add it to LuaLS as a library.')
    ..writeln('---Generator: lualike.docs')
    ..writeln('---Schema: 1');
  if (packageVersion != null) {
    buf.writeln('---Package version: $packageVersion');
  }
  buf.writeln();

  final emittedTables = <String>{};
  for (final lib in libraries) {
    final docs = lib.getDocs();
    if (docs.isEmpty) {
      continue;
    }
    final libraryName = _libraryDocName(lib, docs);
    if (libraryName != 'base') {
      _emitLuaLsTable(buf, libraryName, emittedTables);
    }

    for (final entry in docs.entries) {
      final qualifiedName = _qualifiedFunctionName(libraryName, entry.key);
      _emitLuaLsFunction(
        buf,
        qualifiedName: qualifiedName,
        doc: entry.value,
        emittedTables: emittedTables,
      );
    }
  }

  return buf.toString();
}