From 84aa3d3cba9a96d70c9ed9aa46499ccd16677974 Mon Sep 17 00:00:00 2001 From: danymat Date: Tue, 1 Feb 2022 18:56:51 +0100 Subject: [PATCH] doc: Add section `:h neogen-template-api` --- lua/neogen/configurations/c.lua | 2 +- lua/neogen/configurations/csharp.lua | 2 +- lua/neogen/configurations/go.lua | 2 +- lua/neogen/configurations/java.lua | 2 +- lua/neogen/configurations/javascript.lua | 2 +- lua/neogen/configurations/lua.lua | 2 +- lua/neogen/configurations/php.lua | 2 +- lua/neogen/configurations/python.lua | 6 +-- lua/neogen/configurations/rust.lua | 4 +- lua/neogen/configurations/typescript.lua | 2 +- lua/neogen/utilities/template.lua | 55 +++++++++++++++++++----- 11 files changed, 57 insertions(+), 24 deletions(-) diff --git a/lua/neogen/configurations/c.lua b/lua/neogen/configurations/c.lua index b9510b7..152cccb 100644 --- a/lua/neogen/configurations/c.lua +++ b/lua/neogen/configurations/c.lua @@ -169,7 +169,7 @@ local c_config = { granulator = nil, generator = nil, - template = template:add_default_template("doxygen"), + template = template:add_default_annotation("doxygen"), } return c_config diff --git a/lua/neogen/configurations/csharp.lua b/lua/neogen/configurations/csharp.lua index 6986dab..3e3b887 100644 --- a/lua/neogen/configurations/csharp.lua +++ b/lua/neogen/configurations/csharp.lua @@ -116,5 +116,5 @@ return { }, }, }, - template = template:add_default_template("doxygen"):add_template("xmldoc"), + template = template:add_default_annotation("doxygen"):add_annotation("xmldoc"), } diff --git a/lua/neogen/configurations/go.lua b/lua/neogen/configurations/go.lua index 94bda68..4efd4e4 100644 --- a/lua/neogen/configurations/go.lua +++ b/lua/neogen/configurations/go.lua @@ -27,5 +27,5 @@ return { }, }, - template = template:config({ use_default_comment = true }):add_default_template("godoc"), + template = template:config({ use_default_comment = true }):add_default_annotation("godoc"), } diff --git a/lua/neogen/configurations/java.lua b/lua/neogen/configurations/java.lua index be12971..83ae439 100644 --- a/lua/neogen/configurations/java.lua +++ b/lua/neogen/configurations/java.lua @@ -113,5 +113,5 @@ return { }, }, - template = template:add_default_template("javadoc"), + template = template:add_default_annotation("javadoc"), } diff --git a/lua/neogen/configurations/javascript.lua b/lua/neogen/configurations/javascript.lua index 6b998f1..d0871c7 100644 --- a/lua/neogen/configurations/javascript.lua +++ b/lua/neogen/configurations/javascript.lua @@ -112,5 +112,5 @@ return { }, }, - template = template:add_default_template("jsdoc"), + template = template:add_default_annotation("jsdoc"), } diff --git a/lua/neogen/configurations/lua.lua b/lua/neogen/configurations/lua.lua index 8d3ec7e..4551f24 100644 --- a/lua/neogen/configurations/lua.lua +++ b/lua/neogen/configurations/lua.lua @@ -149,5 +149,5 @@ return { granulator = nil, generator = nil, - template = template:config({ use_default_comment = true }):add_default_template("emmylua"):add_template("ldoc"), + template = template:config({ use_default_comment = true }):add_default_annotation("emmylua"):add_annotation("ldoc"), } diff --git a/lua/neogen/configurations/php.lua b/lua/neogen/configurations/php.lua index f15f1ff..c73f172 100644 --- a/lua/neogen/configurations/php.lua +++ b/lua/neogen/configurations/php.lua @@ -78,5 +78,5 @@ return { }, }, }, - template = template:add_default_template("phpdoc"), + template = template:add_default_annotation("phpdoc"), } diff --git a/lua/neogen/configurations/python.lua b/lua/neogen/configurations/python.lua index 0c07c90..934cafe 100644 --- a/lua/neogen/configurations/python.lua +++ b/lua/neogen/configurations/python.lua @@ -250,7 +250,7 @@ return { end end, }) - :add_default_template("google_docstrings") - :add_template("numpydoc") - :add_template("reST"), + :add_default_annotation("google_docstrings") + :add_annotation("numpydoc") + :add_annotation("reST"), } diff --git a/lua/neogen/configurations/rust.lua b/lua/neogen/configurations/rust.lua index f494f21..0056963 100644 --- a/lua/neogen/configurations/rust.lua +++ b/lua/neogen/configurations/rust.lua @@ -91,6 +91,6 @@ return { template = template :config({ use_default_comment = true }) - :add_template("rustdoc") - :add_default_template("rust_alternative"), + :add_annotation("rustdoc") + :add_default_annotation("rust_alternative"), } diff --git a/lua/neogen/configurations/typescript.lua b/lua/neogen/configurations/typescript.lua index 0725f28..b528af8 100644 --- a/lua/neogen/configurations/typescript.lua +++ b/lua/neogen/configurations/typescript.lua @@ -134,5 +134,5 @@ return { }, }, - template = template:add_default_template("jsdoc"), + template = template:add_default_annotation("jsdoc"), } diff --git a/lua/neogen/utilities/template.lua b/lua/neogen/utilities/template.lua index 249f3ff..d9adea9 100644 --- a/lua/neogen/utilities/template.lua +++ b/lua/neogen/utilities/template.lua @@ -5,17 +5,20 @@ --- as well as providing custom configurations in order to be precise about --- how to customize the annotations. --- +--- We exposed some API to help you customize a template, and add your own custom annotations +--- For this, please go to |neogen.template_api| +--- ---@type neogen.TemplateConfig --- --- Default values: ----@tag neogen.template_configuration ----@toc_entry Customize templates for a language +---@tag neogen-template-configuration +---@signature +---@toc_entry Configurations for the template table ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section) -local template_configuration = { +local neogen_template = { annotation_convention = nil, use_default_comment = false, } - --- # neogen.TemplateConfig~ --- ---@class neogen.TemplateConfig see |template_config| @@ -63,14 +66,38 @@ local template_configuration = { --- < -- TODO: Add section to tell about annotation convention ----Update template configuration ----@param tbl neogen.TemplateConfig -template_configuration.config = function(self, tbl) +--- # Templates API~ +--- +--- Welcome to the neogen API section for templates. +--- +--- A template is an entity relative to a filetype that holds configurations for how to place +--- annotations. +--- With it, you can add an annotation convention to a filetype, change defaults, +--- and even provide your own annotation convention ! +--- I exposed some API's, available after you get a template. +--- Please see |neogen.get_template()| for how to get a template. +--- +--- Example: +--- > +--- neogen.get_template("python"):config({ annotation_convention = ... }) +--- < +---@tag neogen-template-api +---@toc_entry API to customize templates + +--- Updates a template configuration +---@signature :config(tbl) +---@param tbl neogen.TemplateConfig Override the template with provided config +---@tag neogen-template-api.config() +neogen_template.config = function(self, tbl) self = vim.tbl_extend("force", self, tbl) return self end -template_configuration.add_template = function(self, name) +--- Add an annotation convention to the template +---@signature :add_annotation(name) +---@param name string The name of the annotation convention +---@tag neogen-template-api.add_annotation() +neogen_template.add_annotation = function(self, name) local ok, _t = pcall(require, "neogen.templates." .. name) if not ok then @@ -81,10 +108,16 @@ template_configuration.add_template = function(self, name) return self end -template_configuration.add_default_template = function(self, name) +--- Add an annotation convention to the template and make it the default +---@signature :add_default_annotation(name) +---@param name string The name of the annotation convention +---@tag neogen-template-api.add_default_annotation() +neogen_template.add_default_annotation = function(self, name) self.annotation_convention = name - self = self:add_template(name) + self = self:add_annotation(name) return self end -return template_configuration +-- TODO: add API to create your own annotation convention + +return neogen_template