Feature request: Analog of diff for custom declared function

[TIMONz1535]

I want to write new declaration for some functions, for example, to add generics or some complex types (@nodiscard or even integer) that the wiki does not allow us to use.

However, if I do this in a "custom directory", then I completely replace the function description and eventually it becomes obsolete.

I would prefer to be able to write a "diff" when I can change the parameter types, but not change the parameter name/desc with a full method info.

--[[... unchanged info ...]]
---@generic T
---@param metaName `T` --[[... unchanged desc ...]]
---@return T? --[[... unchanged desc ...]]
---@nodiscard
function _G.FindMetaTable(metaName) end

Do you have any ideas on how to do this? I don't mean the real diff that is used in version control systems - maybe it's too complicated.

p.s. But yes, I don't want to write a @nodiscard to everything, it's stupid.

[luttje]

Thanks for the feature request!

Are you talking about changes to documentation that you would make to this repository (for everyone using the garrysmod LuaLS addon)? Or just for yourself (locally)?

If its the former, then I agree that our custom/ directory is very limited in how it can be used to customize docs. Documentation additions like @nodiscard are useful to everyone using this addon imo, so I think we could safely add them to this repo. I'll think about how we can improve customizing the wiki scraper output.

If its the latter then I'm not sure LuaLS supports overriding our definitions locally. Instead I think you could fork the library branch and make changes to that in the fork. You could clone that locally and add it to your workspace.library config. Later when we update this addon you could sync it, resolving any merge conflicts manually (which would need to be done anyway if there was some sort of diff system)

Let me know what you think.

[TIMONz1535]

Yes, changes to this repository for everyone.

Just so that I don't have to copy a lot of wiki methods to make them better for LuaLS. Then after a few months it will be outdated, so it always need to be updated manually = bad. I can't repeat the same thing on the wiki because of the Lua/wiki principles.

For example, there is no place for integer type in the wiki, because its a fake type by LuaLS and unexists on LuaJIT and Lua 5.1 but still very useful. A description of generics is simply impossible in any form on the wiki.

As a result, I want to get non-destructive changes pipeline 🙃

Not really on the topic, but we also have not well wiki scrapped builtin Lua definitions (like string lib) and very good sumneko's builtin Lua definitions. To be honest, I dont want to delete wiki definitions, but I want to synchronize parameter types (if it cannot be repeated in the wiki). I could use "diff" as a temporary solution, but a current complete redefinition seems wrong to me.

[luttje]

@TIMONz1535 I think that last comment relates to #23.

On the topic of allowing customization in this repo, I'm thinking that we could have custom TypeScript snippets in our custom/ folder. Those could manipulate the pages as they're being written here:

glua-api-snippets/src/api-writer/glua-api-writer.ts

Lines 79 to 110 in 70f58cc

	public writePage(page: WikiPage) {
	const fileSafeAddress = safeFileName(page.address, '.');
	if (this.pageOverrides.has(fileSafeAddress)) {
	let api = '';
	if (isClassFunction(page))
	api += this.writeClassStart(page.parent, undefined, undefined, undefined, page.deprecated);
	else if (isLibraryFunction(page))
	api += this.writeLibraryGlobalFallback(page);
	api += this.pageOverrides.get(fileSafeAddress);
	return `${api}\n\n`;
	} else if (isClassFunction(page))
	return this.writeClassFunction(page);
	else if (isLibraryFunction(page))
	return this.writeLibraryFunction(page);
	else if (isHookFunction(page))
	return this.writeHookFunction(page);
	else if (isPanel(page))
	return this.writePanel(page);
	else if (isPanelFunction(page))
	return this.writePanelFunction(page);
	else if (isEnum(page))
	return this.writeEnum(page);
	else if (isStruct(page))
	return this.writeStruct(page);
	else if (isLibrary(page))
	return this.writeLibraryGlobal(page);
	else if (isClass(page))
	return this.writeClassGlobal(page);
	}

My thinking is that we can write the snippets in a way that they can be tested. We write them so the code snippets error when docs change too much. In that case when a workflow on GitHub fails, we get a clear notification, instead of a diff or static file silently failing to properly replace.

I'm thinking the implementation could look something like:

// psuedo-code
public writePage(page: WikiPage) {
  const fileSafeAddress = safeFileName(page.address, '.');
  const overrideSnippetFunction = loadOverrideSnippet(fileSafeAddress);

  // Do preprocessing here, so the snippets work with simple data

  if (overrideSnippetFunctions) {
    return overrideSnippetFunction(page)
  }

  // ... Old code (minus pageOverrides which would be replaced by the new snippet systme)
}

Where snippets would be:

// file: custom/vgui.Create.ts
import { SnippetFunctionType } from 'utils/snippets.js';

// psuedo-code
export default <SnippetFunctionType> function(page: WikiPage, assert: AssertFunction): string {
  // We want to fail if vgui.Create no longer gets any of the arguments we expect
  assert(page.type === 'libraryfunc');
  assert(page.arguments.length === 3);
  assert(page.arguments[0].type === 'string');
  assert(page.arguments[1].type === 'Panel|nil');
  assert(page.arguments[2].type === 'string|nil');
  
  return `<!-- custom output for vgui.Create using information in WikiPage, to add generics for example -->`
}

Open to feedback, let me know if this is overkill

[TIMONz1535]

I like the idea, but I don't want to return pre-formatted text, could I work with structures to improve the definition? For example

// psuedo-code vgui.Create 

assert(page.arguments.length > 0 && page.arguments[0].type === 'string');
page.arguments[0].type = '`T`';
assert(page.returns.length > 0 && page.returns[0].type === 'Panel|nil');
page.returns[0].type = 'T?';

assert(page.returns.length === 1);
page.returns.push(<FunctionReturn> {
          name: 'secondRet',
          type: 'T',
          description: 'an example'
        });

page.prefix = '---@generic T: Panel';
page.postfix = '---@nodiscard\n---@any_other_lines_before_function';

// done
}

I'm also afraid that if there is a separate file for each method, then there will be hundreds of small files, in which, for example, there will be one postfix @nodiscard.

at the same time, it could be one file with a set of functions (grouped by library or logic), or maybe even one function that checks the page.address with a local defined list.

[luttje]

Sure one file could work too, I'm down for that idea. We could add imports to other files to provide structure if it gets out of hand in the future.

[luttje]

Noting that this could also allow generating the @overloads for hook.Add mentioned in #39.

For that we'd have to supply an override function with a way to see all scraped hooks, which are only available after all pages have been scraped:

glua-api-snippets/src/cli-scraper.ts

Line 146 in 70f58cc

const results = await Promise.allSettled(queue);

So perhaps this system we're thinking about could have several events/hooks it could respond to:

• prePageWriting(page: WikiPage, assert: AssertFunction): string to modify prefix/postfix
  For Overload hook.Add's eventName with events defined in the wiki #39 I would imagine adding a %REPLACEWITHOVERLOADS% placeholder

• postPagesWritten(pages: SavedWikiPage[]) where one could replace any placeholders inside any wiki page.
  Accessing/changing a page's generated definitions would automatically read it from disk and save it after this, so the snippets don't have to handle reading/writing the definition files.
  For Overload hook.Add's eventName with events defined in the wiki #39 I would imagine this is where %REPLACEWITHOVERLOADS% is replaced with a bunch of generated --- @overload fun(eventName: "Move", identifier: any, func: fun(ply: Player, mv: CMoveData): boolean?)

Let me know if there's more events that might be useful.

[TIMONz1535]

I think this should be done under the hood of the plugin, not by hacking hook function definitions.

If you were referring to "overloads" from multiple variations of the function, this should be done by wiki <args> Argument Overload https://wiki.facepunch.com/gmod/Global.Angle

I was working on a plugin for NetworkVar and AccessorFunc which have similar needs. And I came to the conclusion that I need to do this through OnTransformAst/VM.OnCompileFunctionParam not with a OnSetText. I think this issue is not about that, so I created another one #74

[luttje]

Hmm I think for hook.Add we shouldn't pollute the wiki with information that's found elsewhere on the wiki. Adding overloads for each hook would create a massive page for hook.Add. Instead, how I read #39 and relate it to this, is to create a way to add those ---@overload fun... for each existing GM hook and gameevent and place them right before this line in our final definitions:

glua-api-snippets/library/hook.lua

Line 23 in 5011495

function hook.Add(eventName, identifier, func) end

To clarify how I envision these customization functions I'll create a prototype (or just implement it). However I'll likely not be making time for that in the coming months. So for now the custom/ folder will have to do.