From 61e9137394fc5229e582a64316c2ffef55d8d7af Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 1 Sep 2024 13:01:24 -0700 Subject: docs: misc #28970 --- runtime/doc/develop.txt | 37 ++++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 15 deletions(-) (limited to 'runtime/doc/develop.txt') diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index d7837dc2fe..41bb90299b 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -138,15 +138,15 @@ DOCUMENTATION *dev-doc* - Write docstrings (as opposed to inline comments) with present tense ("Gets"), not imperative ("Get"). This tends to reduce ambiguity and improve clarity by describing "What" instead of "How". > - GOOD: + ✅ OK: /// Gets a highlight definition. - BAD: + ❌ NO: /// Get a highlight definition. - Avoid starting docstrings with "The" or "A" unless needed to avoid ambiguity. This is a visual aid and reduces noise. > - GOOD: + ✅ OK: /// @param dirname Path fragment before `pend` - BAD: + ❌ NO: /// @param dirname The path fragment before `pend` - Vim differences: - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog @@ -329,13 +329,20 @@ Where possible, these patterns apply to _both_ Lua and the API: - When accepting a buffer id, etc., 0 means "current buffer", nil means "all buffers". Likewise for window id, tabpage id, etc. - Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()| -- Any function signature that accepts a callback function should define the - callback as the LAST parameter, if possible. This improves readability of - calls by placing the less "noisy" arguments near the start. > - GOOD: - filter(table, opts, function() … end) - BAD: - filter(function() … end, table, opts) +- Any function signature that accepts a callback (example: |table.foreach()|) + should place it as the LAST parameter (after opts), if possible (or ALWAYS + for "continuation callbacks"—functions called exactly once). + - Improves readability by placing the less "noisy" arguments near the start. + - Consistent with luv. + - Useful for future async lib which transforms functions of the form + `function(, cb())` => `function() -> `. + - Example: >lua + -- ✅ OK: + filter(…, opts, function() … end) + -- ❌ NO: + filter(function() … end, …, opts) + -- ❌ NO: + filter(…, function() … end, opts) - "Enable" ("toggle") interface and behavior: - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the the "global" enablement of a feature. @@ -566,10 +573,10 @@ a good name: it's idiomatic and unambiguous. If the package is named "neovim", it confuses users, and complicates documentation and discussions. Examples of API-client package names: -- GOOD: nvim-racket -- GOOD: pynvim -- BAD: python-client -- BAD: neovim_ +- ✅ OK: nvim-racket +- ✅ OK: pynvim +- ❌ NO: python-client +- ❌ NO: neovim_ API client implementation guidelines ~ -- cgit From 3f6bc34e663c62bc8899dcdc65bf204b2ccfdaec Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 24 Sep 2024 04:46:50 -0700 Subject: docs: lua error patterns #30240 Co-authored-by: Mathias Fussenegger Co-authored-by: Ananth Bhaskararaman --- runtime/doc/develop.txt | 43 ++++++++++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 13 deletions(-) (limited to 'runtime/doc/develop.txt') diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 41bb90299b..9dbdaec31c 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -307,19 +307,36 @@ See also |dev-naming|. easier to inspect and print, and inherently compatible with all Lua plugins. (This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.) - stdlib functions should follow these common patterns: - - accept iterable instead of table - - exception: in some cases iterable doesn't make sense, e.g. spair() sorts - the input by definition, so there is no reason for it to accept an - iterable, because the input needs to be "reified"; it can't operate on - a "stream". - - return iterable instead of table - - mimic the pairs() or ipairs() interface if the function is intended to be - used in a "for" loop. - - when a result-or-error interface is needed, return `result|nil, nil|errmsg`: > - ---@return Foo|nil # Result object, or nil if not found. - ---@return nil|string # Error message on failure, or nil on success. -< - - Examples: |vim.ui.open()| |io.open()| |luv-error-handling| + - Return |lua-result-or-message| (`any|nil,nil|string`) to communicate + failure, or choose from |dev-error-patterns| when appropriate. + - Accept iterable instead of only table. + - Note: in some cases iterable doesn't make sense, e.g. spair() sorts the + input by definition, so there is no reason for it to accept an iterable, + because the input needs to be "reified"; it can't operate on a "stream". + - Return an iterable (generator) instead of table, if possible. + - Mimic the pairs() or ipairs() interface if the function is intended for + use in a |for-in| loop. + + *dev-error-patterns* +To communicate failure to a consumer, choose from these patterns (in order of +preference): +1. `retval, errmsg` + - When failure is normal, or when it is practical for the consumer to + continue (fallback) in some other way. See |lua-result-or-message|. +2. optional result, no errormsg + - Special case of 1. When there is only a single case of "doesn't exist" + (e.g. cache lookup, dict lookup). +3. `error("no luck")` + - For invalid state ("must not happen"), when failure is exceptional, or at + a low level where the consumers are unlikely to handle it in a meaningful + way. Advantage is that propagation happens for free and it's harder to + accidentally swallow errors. (E.g. using + `uv_handle/pipe:write()` without checking return values is common.) +4. `on_error` parameter + - For async and "visitors" traversing a graph, where many errors may be + collected while work continues. +5. `vim.notify` (sometimes with optional `opts.silent` (async, visitors ^)) + - High-level / application-level messages. End-user invokes these directly. *dev-patterns* Interface conventions ~ -- cgit From b45c50f3140e7ece593f2126840900f5cc3d39ea Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 4 Oct 2024 02:13:31 -0700 Subject: docs: render `@since` versions, 0 means experimental #30649 An implication of this current approach is that `NVIM_API_LEVEL` should be bumped when a new Lua function is added. TODO(future): add a lint check which requires `@since` on all new functions. ref #25416 --- runtime/doc/develop.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'runtime/doc/develop.txt') diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 9dbdaec31c..ee7fa808f2 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -247,6 +247,10 @@ Docstring format: - References are written as `[tag]` - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` +- Use `@since ` to note the |api-level| when the function became + "stable". If `` is greater than the current stable release (or + 0), it is marked as "experimental". + - See scripts/util.lua for the mapping of api-level to Nvim version. - Use `@nodoc` to prevent documentation generation. - Use `@inlinedoc` to inline `@class` blocks into `@param` blocks. E.g. >lua @@ -271,7 +275,7 @@ Docstring format: - {somefield}? (integer) Documentation for some field < -- Files which has `@meta` are only used for typing and documentation. +- Files declared as `@meta` are only used for typing and documentation (similar to "*.d.ts" typescript files). Example: the help for |vim.paste()| is generated from a docstring decorating vim.paste in runtime/lua/vim/_editor.lua like this: > @@ -288,6 +292,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: > --- end)() --- ``` --- + --- @since 12 --- @see |paste| --- --- @param lines ... -- cgit From 61f1b091ea97793f9b644cebf6c84cf6bbb4f0bc Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 7 Oct 2024 08:27:38 -0700 Subject: docs: dev-arch, focusable windows #30510 - 'statuscolumn' is no longer experimental - add tags for popular searches on neovim.io --- runtime/doc/develop.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/doc/develop.txt') diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index ee7fa808f2..a61c569a67 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -7,8 +7,8 @@ Development of Nvim *development* *dev* This reference describes design constraints and guidelines, for developing -Nvim applications or Nvim itself. -Architecture and internal concepts are covered in src/nvim/README.md +Nvim applications or Nvim itself. See |dev-arch| for discussion of Nvim's +architecture and internal concepts. Nvim is free and open source. Everybody is encouraged to contribute. https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md -- cgit