Git Product home page Git Product logo

vimdoc's Introduction

Vimdoc - Helpfile generation for vim plugins

Vimdoc generates vim helpfiles from documentation in vimscript files. You annotate vimscript like this:

""
" This is my function. It does different things to the {required} argument,
" depending upon the [optional] argument.
function! myplugin#MyFunction(required, ...) abort
  ...
endfunction

and you get helpfiles that look like this:

===========================================================================
FUNCTIONS                                              *myplugin-functions*

myplugin#MyFunction({required}, [optional])         *myplugin#MyFunction()*
  This is my function. It does different things to the {required} argument,
  depending upon the [optional] argument.

This allows you to keep all of your documentation in one place (the code!) and generate nicely formatted help files without manually aligning text and adding tags and so on.

To see an example of vimdoc in use, see maktaba, specifically the helloworld example plugin therein, which shows some of the basics.

Vimdoc is unstable. It's a collection of regexes and hacks masquerading as a complete vim documentation tool. But it works, and it's useful, and it will continue to be useful while it gets cleaned up.

Installation

Use setup.py to install vimdoc in the usual way. On most systems, this is:

python setup.py config
python setup.py build
sudo python setup.py install

Execution

Run vimdoc on a directory containing a plugin. It will generate a help file in the 'doc' directory of that plugin. For example:

vimdoc plugins/myplugin

will generate the helpfile

plugins/myplugin/doc/myplugin.txt

Usage

Vimdoc operates on comment blocks, which are a continuous group of lines starting with the "" header:

""
" Documentation for function
function! ...

Vimdoc automatically recognizes the type of these blocks. It can detect the following:

  • function definitions
  • command definitions
  • global settings
  • maktaba flags
  • plugin descriptions (at the top of plugin files)

The names of functions/commands/settings are automatically detected from the line below the comment block. The arguments for functions/commands are automatically deduced from the body of the text and (in the case of functions) from the name of the arguments in the function definition, as follows:

  • If the names of all mentioned required arguments in the comment block match the names of the arguments in the function definition, then the required arguments are ordered according to their placement in the function definition.
  • Otherwise, the names used in the comment block are used instead of the names used in the function definition, in the order of mention in the comment block.
  • Optional arguments (which cannot be named in a function definition, as their existence is indicated only by an ellipsis) are used as named in the comment block, in the order of mention.

These defaults are usually correct, but can be overridden.

Vimdoc has a number of builtin directives, which are marked by @ signs.

It also detects your plugin's addon-info.json file if present (see the documentation and relevant VAM help).

Block Directives

Block directives take up an entire line in the comment block. They look like this:

""
" @usage req1 req2 \[opt1] \[opt2]
" description...
function! MyFunction(badName1, badName2, ...)

Available block directives include:

  • @stylized name allows you to define the stylized version of a plugin name (for example, myplugin could be stylized as "My Plugin").
  • @library marks your plugin as a library plugin. This makes functions public by default.
  • @public marks a function public. In most plugins, functions are private by default, though this default may be overridden on a per-plugin basis.
  • @private marks a function private.
  • @section name[, id] allows you to write a new section for the helpfile. The id will be a lowercased version of name if omitted.
  • @parentsection id defines the current section as a child of the given section. Must be contained within a @section block.
  • @subsection name defines a subsection (heading) within a section block.
  • @backmatter id declares a block to be rendered at the end of the given section.
  • @order ... allows you to define the order of the sections. Sections with a @parentsection may not be included here.
  • @dict name (above blank lines) allows you to define a new dictionary.
  • @dict dict.fn (above a function) allows you to add a function to a dictionary.
  • @usage ... allows you to rename and reorder the arguments of a function or command.
  • @all denotes that the remainder of the block will be included in all usages (in the case of multiple overloaded usages).
  • @function ... allows you to alter the function tag directly, for when @usage does not offer enough control.
  • @command ... allows you to alter the command tag directly, for when @usage does not offer enough control.
  • @setting name declares a setting (global or per-buffer configuration variable).
  • @default arg=value describes the default value of an optional arg.
  • @throws exception describes the type of exceptions that a function or command may throw.
  • @deprecated reason marks a command or function as deprecated and excludes it from the docs.

The global directives (@stylized, @order, and @library) are all detected from inside a @section block (usually the Introduction section).

Inline Directives

Inline directives occur in the body of comment blocks. Most take one argument enclosed in parenthesis.

  • @function(name) generates a link to a function defined in the plugin.
  • @command(name) generates a link to a command defined in the plugin.
  • @flag(name) generates a link to a flag defined in the plugin.
  • @setting(name) generates a link to a setting defined in the plugin.
  • @section(id) generates a link to a section defined in the plugin.
  • @dict(name) generates a link to a dictionary defined in the plugin.
  • @plugin(attr) Outputs some plugin data, such as the name or author. attr must be one of stylized, name, or author. If the attr (and parenthesis) are left off, stylized is used.

Other Metadata

Some metadata for your plugin is not configured via vimdoc directives, but comes from other sources.

By default, the name for the plugin is the name of its top-level directory. If an addon-info.json file is present and contains an explicit "name" field, vimdoc will use that plugin name instead. This is important if the plugin lives in a directory with a "vim" prefix or suffix, such as "vim-dispatch". This plugin name will appear in the helpfile header and determine the name of the helpfile itself.

Vimdoc will also take the author and description values from the "author" and "description" fields in addon-info.json.

Syntax

Vimdoc syntax is reminiscent of helpfile syntax.

  • Use quotes to reference settings, such as 'filetype'.
  • Use brackets to reference [optional] function arguments.
  • Use braces to reference {required} function arguments.
  • Use |pipes| to link to tags in other helpfiles.

Helpfile Structure

The generated helpfile for a plugin has the following structure:

Header
Table of Contents
1. Introduction
2. Configuration
3. Commands
5. Settings
6. Dictionaries
7. Functions
8. Mappings
9. About

All of these (except Header and Table of Contents) are optional and predicated upon the comment blocks existing in the right places in the file. You may eliminate sections by omitting the comment blocks. You may add custom sections with the @section directive.

Header

The header is a simple line or two following the vim helpfile style guide. It looks something like:

*myplugin*     My Plugin’s Tagline
author                                                *Stylized-Name*

Table of Contents

Of the form

=====================================================================
CONTENTS                                          *myplugin-contents*
  1. Introduction                                    |myplugin-intro|
  2. Configuration                                  |myplugin-config|
  ...

And so on for each section.

Introduction

The introductory comment block is used to populate this section.

Configuration

This section contains descriptions of all the flags and settings that were annotated by vimdoc comment blocks.

Any global let command with a doc comment will automatically be detected as a setting:

""
" Enable a thing.
let g:myplugin_enable_thing = 1

You can use the @setting block directive to declare settings vimdoc doesn't recognize:

""
" @setting g:myplugin_secret_number
" A secret number.
echo 'The number is' get(g:, 'myplugin_secret_number', b:changedtick)

""
" @setting b:myplugin_enable_thing
" Enable a thing in the current buffer.

Maktaba flags with doc comments are also automatically recognized:

""
" Supported things.
call s:plugin.Flag('things', ['a', 'b'])

Commands

Contains a list of commands available to the user. Vimdoc understands -bang, -nargs, -range, -count, -register, and -buffer. (It ignores -bar.) It will parse out the arguments in the order that they are mentioned in the comment block above the command and will generate a usage line for the command. For example, the following comment block:

""
" Spawns two new zerglings from the given {hatchery}
" Attacks all units in the selected [range] upon spawning.
" [larva], if given, will be used to spawn the zerglings.
" Otherwise a larva will be selected at random.
" [!] forces the zerglings to spawn even if you don’t have enough
" overlords. Caution: this may make your swarm uncontrollable.
command -range -bang -nargs=+ -bar SpawnZerglings
    \ call zerg#spawn(ZERGLINGS, '<bang>' == '!', <f-args>)

will generate the following usage line:

:[range]SpawnZerglings[!] {hatchery} [larva]

You can override the usage line with the @usage command, which takes a list of arguments. Any arguments that look like vim variable names (\I\i+) will be assumed to be parameters, and their required-ness will be inferred from the docs. You can force required-ness by providing arguments that look like vim variables wrapped in curly (required) or square (optional) brackets. Empty curly brackets stand in for the remainder of the inferred required variables. Empty square brackets stand in for the remainder of the inferred optional variables. For example:

""
" @usage {} [first] []
" Start with {base}, add [second] to [first] and divide by [third].
command SomeCommand ...

generates:

:SomeCommand {base} [first] [second] [third]

For more advanced usage, you may use the @command directive. This is useful either when your command takes a non-standard argument list (like :substitute) or when your command is not recognized by vimdoc (when you :execute 'command' s:name).

The @command directive takes one argument, which is the entire usage line. {} expands to all of the inferred required parameters, [] to all of the inferred optional parameters, and <> to the complete inferred command name with built-in flags included. For example:

""
" @command <>/{pattern}/{string}/[flags] [count]
command -range -bang -nargs=1 Substitute ...

generates the usage line:

:[range]Substitute[!]/{pattern}/{string}/[flags] [count]

An argument which may be given multiple times should be suffixed with an ellipsis. For example, {arg...} documents an argument that may appear once or more and [arg...] denotes an argument that may appear zero or more times.

Sometimes you want a command to have more than one usage. For that you may use more than one usage directive. Example:

""
" @usage {list} {index} {item}
" Add {item} to {list} at {index}.
" @usage {dict} {key} {value}
" Set {dict} {key} to {value}.
" @all
" WARNING: Will launch the nuclear missiles.

This will generate two docs for the command: one for list, one for dicts. An @all directive denotes that the remainder of the block will be included in all usages. In the above example, the warning will be included in both the list and the dict version of the command docs.

Dictionaries

Vimscript kinda-sorta supports object oriented programming via dictionaries with functions attached. (See :help Dictionary-function.) Vimdoc helps you group these dictionaries and their methods in one place in the documentation.

You may describe a dictionary object type using the @dict annotation in a comment block that is above a blank line. Then you may annotate the dictionary functions with the @dict directive to have them grouped with the dictionary description. (Such functions will not be listed in the functions section.)

Functions

Function documentation is very similar to command documentation.

The order of required parameters is inferred by looking at the function declaration.

The order of optional parameters is inferred by the order they are mentioned in the comment block. Use the @usage command as described in the Command section to correct the order of optional arguments.

Functions may have multiple usages just like commands. Functions are not exposed in the help docs by default. Use @public to make them public by default.

@function can be used to tell vimdoc about a non-obvious function (such as one created by :execute). (), {}, and [] expand as in @command.

vimdoc's People

Contributors

dbarnett avatar freed-wu avatar malcolmr avatar martindemello avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

vimdoc's Issues

Vimdoc should document mappings

There should be a way to document individual mappings so they're listed in the mappings section of help files.

We should probably just have an explicit @mapping KEYS [mode] rather than trying to be clever and parse :map commands, at least for a first pass, because there are a lot of variants and a lot of code will use :execute and other high-level code structures to define mappings that might be hard to get right.

Document list capabilities

The various types of list (see output.py HelpFile.WriteParagraph) are poorly documented and stringly typed. We should explicitly differentiate between the different types of lists in the parser.

Refactor module.py, it is repetitive and brittle.

Module.Close is a big offender. (As this code is cleaned, it should be come easier to validate that all elements of the 'order' setting are actually existing sections. error.NoSuchSection should be created for this purpose.)

Module.Chunks will be able to be drastically simplified after Module.Close is cleaned up, I think.

Add tests

Tests would be nice.

Vimdoc is currently pretty hacky and fairly buggy.

[Maktaba integration] vimdoc should document plugin[*] flags

For a user that just installs a given maktaba plugin and hasn't studied the intricacies of maktaba, it takes some sleuthing to figure out that a given plugin can be configured using maktaba's standard plugin[autocmds], plugin[mappings], etc.

vimdoc should automatically detect the standard maktaba plugin/.vim and instant/.vim files and generate flag documentation for relevant flags in each plugin's docs. We can even detect exactly which files exist with the maktaba#plugin#Enter prelude and generate exactly the right keys.

Note that plugins may define their own vimdoc or default values for plugin[*] and instant[*] flags, and we'd need to make sure not to clash with those.

Vimdoc needs some way to continue long @throws lines

We got rid of pipe line continuations in vimdoc. That means currently there's no way to have an @throws line longer than 80 characters.

Given this vimdoc comment:

" @throws Ambiguous if {name} refers to multiple plugins/packages within one
" source.

Vimdoc currently creates an awkward line wrap in the output:

Throws ERROR(Ambiguous) if {name} refers to multiple plugins/packages within
 one
 source.

We discussed having the convention for continuing directive lines be a standard 4-space indent:

" @throws Ambiguous if {name} refers to multiple plugins/packages within one
"     source.

Other directives like @tagline and @order will need this as well.

Vimdoc gets confused around angle braces

Vimdoc seems to get tripped up on angle braces and try to treat them as code blocks even if they're in the midst of other text and not at the start of the line.

I had a vimdoc comment like this over a function

""
" Blah blah blah:
"   <module 'foo.bar' from 'repopath/foo/python/foo/bar.py'>

and the generated docs looked like this:

Blah Blah Blah:   <module 'foo.bar' from
'repopath/foo/python/foo/bar.py'
>
<

Vimdoc chokes on brackets inside code examples

  1. Vimdoc should recognize a whole code block as special and not try to pick directives, parameter names, or any special symbols out of it.
  2. If a function does accept ..., we won't hit this case and will be silently adding bogus arguments into the vimdoc. We can work around this case in the short term with an explicit @Usage.
  3. We could tighten the regex to not accept foo[bar] or [bar]foo and avoid some false positives. That might break potentially useful syntax like "[foo]s" or "[foo]-like", but that's probably poor style and rare in practice anyway.
  4. We might want to add syntax to escape brackets with backslashes. (Note: vim help files will still highlight them as args unless we dump literal backslashes in the generated docs).

...

As far as tightening the regex:

  1. We could tighten the regex to not accept foo[bar] or [bar]foo and avoid some false positives. That might break potentially useful syntax like "[foo]s" or "[foo]-like", but that's probably poor style and rare in practice anyway.

I did run into a real-world case for looser matching: syntax like [foo]'s is occasionally useful. For example:

 " Gets absolute file path to [path]'s package directory.

It's not an "absolute must" to support syntax like that, but now we have a non-contrived case where it would be useful.

Remove support for implicit intro and about sections

The first and last comment blocks in the "main file" are implicitly taken as the intro and about sections. The "main file" is a legacy thing we're getting rid of (#24), and it's better to be explicit anyway.

We should stop reading comment blocks as vimdoc sections unless they have an explicit @section directive.

Validate inline directives

Broken inline directives fail to cause errors. This can be fixed by expanding all inline directives that are in front of parens. (See output.py Helpfile.Expand.)

All errors should mention which plugin they came from

If you're generating docs for a long list of plugins (e.g., in a script), errors that don't give a file name or line number can be hard to troubleshoot because you have no idea which plugin was being processed when the error was encountered. We should make sure to include some mention of the plugin being processed for all errors, or at least those that don't have file name / line number info.

A trivial way to do this would be to print "Processing plugin XYZ" to STDERR before processing each plugin.

Deprecate @tagline and @author

The @tagline and @author directives are now legacy fallbacks only used if the "description" and "author" fields aren't detected in addon-info.json.

We should mention addon-info.json in the documentation and mention that the legacy tags are deprecated. We can probably go ahead and make vimdoc fail with an informative error instead of printing warnings given our disclaimer in the README that vimdoc is unstable.

@all directive broken

The @all directive seems to be completely broken. Trying to use it causes this error:

Traceback (most recent call last):
  File "/usr/bin/vimdoc", line 25, in <module>
    for module in Modules(args.plugin):
  File "~/.local/lib/python2.7/site-packages/vimdoc/module.py", line 300, in Modules
    blocks = list(parser.ParseBlocks(filehandle, filename))
  File "~/.local/lib/python2.7/site-packages/vimdoc/parser.py", line 127, in ParseBlocks
    for lineno, line in EnumerateParsedLines(lines):
  File "~/.local/lib/python2.7/site-packages/vimdoc/parser.py", line 68, in EnumerateParsedLines
    yield i, ParseCommentLine(line)
  File "~/.local/lib/python2.7/site-packages/vimdoc/parser.py", line 109, in ParseCommentLine
    return ParseBlockDirective(*block.groups())
  File "~/.local/lib/python2.7/site-packages/vimdoc/parser.py", line 116, in ParseBlockDirective
    return docline.BLOCK_DIRECTIVES[name](rest)
TypeError: Can't instantiate abstract class All with abstract methods Update

We should fix it so it doesn't crash.

Remove automatic blocks at start-of-file

vimdoc tries to parse the first comment in a file as a vimdoc block even if it doesn't have a comment leader. This makes much less sense after the removal of implicit sections (#40).

We should remove the auto vimdoc block behavior in favor of explicit vimdoc leaders. But first, we'll want to fix the parsing problems at start-of-file (#20) so people can switch to the explicit syntax and issue warnings for implicit syntax so people know they're depending on behavior that's about to change.

Add an HTML output mode

Vimdoc is designed to separate the parser from the outputter. It shouldn't be too difficult to write an html output mode.

Vimdoc can die when referencing a function defined in the same plugin

When I put @function(maktaba#error#Shout) in library.vim, vimdoc dies because it can't find maktaba#error#Shout. Note that there's likely some randomness involved here depending upon which plugin file is loaded when. Vimdoc needs to load all files before outputting any, so that it's able to avoid "function not found" errors in this case.

@section id parameter is broken

"@section name" without id throws exception

The id arg to the @section directive is supposed to be optional, but attempting to leave it out results in an error:

 Traceback (most recent call last):
   File "/usr/local/google/home/dbarnett/.local/bin/vimdoc", line 25, in <module>
     for module in Modules(args.plugin):
   File "/usr/local/google/home/dbarnett/.local/lib/python2.7/site-packages/vimdoc/module.py", line 343, in Modules
     module.Close()
   File "/usr/local/google/home/dbarnett/.local/lib/python2.7/site-packages/vimdoc/module.py", line 197, in Close
     raise error.NeglectedSections(known)
 vimdoc.error.NeglectedSections: Sections set([None, 'config', 'functions']) not included in ordering.

The design doc says "It is optional. If omitted, it is the name in lowercase."

Add vimdoc @tag directive to render arbitrary help file tags

Vimdoc supports auto-generated tags for most documentation items (sections, functions, commands, etc.), but doesn't have a way to render arbitrary tags.

For instance, something like this would be useful for the maktaba docs:

" @subsection Default Flags
" @tag plugin[]
" @tag plugin[commands]
" @tag plugin[settings]
" @tag plugin[autocmds]
" @tag plugin[mappings]
" @tag instant[]
" Maktaba provides a few built-in flags in every plugin that…

It might also be worth having a corresponding @link(TAG) notation for links instead of using literal helpfile link syntax, "|TAG|", so it works better for generated web documentation. But it would also be possible to process the pipe syntax explicitly and render appropriate web links in web documentation, so maybe we don't need a special directive for it.

We could cross that bridge when we come to it, of course. Or when we get around to open-sourcing vimdoc, at least.

Vimdoc mis-parses doc comments on first line of file

If the first line of a file contains a vimdoc leader, the first quote character leaks into the vimdoc.

For example, vimdoc parses:

1 ""
2 " @section Introduction, intro
3 " Stuff stuff stuff

and renders it in the help file as:

INTRODUCTION

" Stuff stuff stuff

If you strip off one quote character, vimdoc renders it as it should have been with two quotes.

What does @all do?

I noticed we have an @all directive, but it's not documented at all, I haven't ever seen it used in doc comments, and I can't tell from the code what it's supposed to do.

Does @all do anything useful, or was it a vestige of some code we meant to remove and accidentally left in?

Put line numbers in vimdoc exceptions.

module.py Module.Merge may be a good place to start.

In fact, vimdoc exceptions should be made more intelligent across the board. Line numbers are a good place to start, though.

Make inline directives validate their links

For example, @function(Whatever) should validate that the 'whatever' function exists. (This gets a little tricky if people reference builitn functions or functions from other plugins.)

[Maktaba integration] vimdoc generated help files should generate context boilerplate

From the perspective of someone who doesn't know what maktaba is, the generated help files from vimdoc are pretty opaque. At a minimum, they should automatically include some "how" info about flags and some links into the maktaba docs.

We might want to avoid adding maktaba references to plugins unless we detect they're maktaba plugins (e.g., if they call s:flags.Define, then references to maktaba docs are definitely appropriate).

Remove 'main file' requirement

Vimdoc should be able to use global directives (@author, etc.) no matter where they should fine. (If there's a conflict, it should complain gracefully.)

Deprecate @function(X) with |X()| and @command(Y) with |:Y|

We probably don't need special directives for links to functions and commands. I don't think we realized the () and : were part of the tag when we started; since |X()| and |:Y| unambiguously link to function X and command Y, vimdoc could explicitly recognize these forms and treat them the same as it would treat @function(X) and @command(Y), making those forms unnecessary.

This has 2 advantages: It's more concise, and it's closer to the standard help format, which makes it more natural for plugin authors.

Accept @function(name())

It's easy to get confused and write @function(name()) in vimdoc since the doc tag includes parentheses (name() vs name). We should consider accepting @function(name()) as equivalent to @function(name).

Note this will require changing the inline_directive regex to match the whole thing including the 2nd paren.

Blank lines shouldn't be stripped in example blocks

vimdoc seems to strip blank lines out from the middle of example blocks (the blocks between " > and " < lines).

Given doc comments like

""
" >
"   Foo
"   
"   Bar
" <

the generated docs will look like

>
  Foo
  Bar
<

[Maktaba integration] Document variable types based on maktaba#ensure calls

In keeping with the spirit of DRY, it'd be nice if vimdoc could understand maktaba's variable type checking. Whenever maktaba#ensure calls are present for a:foo, it could add some (optional) information about the type of foo. It could even document the allowable values when appropriate (this would be really handy for enum-like types).

This could be orthogonal to explicitly annotating types in the vimdoc. We could do one or the other, and if we implement both we could just use whichever is provided and warn for conflicts.

Overloading @usage doesn't work properly

The documentation says vimdoc supports multiple @usage directives on the same command or function. This does work for very simple cases, but has quite a few bugs.

Attempting to link to such a function or command triggers errors like "Found multiple FUNCTIONs named Foo".

Each usage is independently checked against the signature and warns if any isn't an exact match for the signature. For instance, the following is perfectly correct, but vimdoc complains about it:

""
" @usage {x}
" @usage {x} {y}
function! foo#Bar(x, ...) abort

An empty @usage directive creates a new separate usage, contrary to what the documentation says. This feature would actually be problematic/surprising in some cases where there actually is a no-arg usage, so if we really do implement it we should consider a more explicit syntax or make sure you can still have an empty @usage directive if it comes before others or something.

Better @setting tag coverage

Vimdoc will generate a @setting tag for very specific syntax like:

""
" Enable a thing.
let g:myplugin_enable_thing = 1

but there are a lot of other common cases that won't be recognized. For instance, the doc comment in:

""
" Enable a thing.
if !exists('g:myplugin_enable_thing')
  let g:myplugin_enable_thing = 1
endif

is ignored. You can get it to work by moving the doc comment down inside the if block, but it's not obvious.

To support this and other complex cases, we should support an explicit @setting NAME block directive that works like @function ... and @command ....

Handle 'exception' types better

The code to check whether a function is an exception (in output.py HelpFile.WriteChunk) is hacky and brittle. We should generalize the mechanism. (The same hack is used in block.py Block.Close, and should be removed from there as well.)

Support external @command and @function names

Currently the inline @command(name) and @function(name) directives can only be used with known commands/functions from the same plugin. Attempting to use them with a function/command from another plugin or built into vim results in a KeyError, e.g.

KeyError: 'COMMAND "somecommand" not found'

This is unintuitive and forces us to use the literal pipe syntax to refer to external commands and functions. We should at least allow any all-lowercase name since that can only refer to a vim built-in and shouldn't be checked against the set of known commands/functions from the plugin. In other words, @command(echo) and @function(empty) should both be valid.

Add --version option to vimdoc script

The vimdoc script should be able to report its own version and exit when invoked with a --version argument.

Currently we list a version number in setup.py following semver.org guidelines, but if you don't know what version of vimdoc you're running, you have to do some investigating to find where the executable came from.

The setup.py file contents aren't accessible to the program itself at runtime. There are various complicated strategies1 for configuring a version number that's accessible both at runtime and install time.

Provide mechanism for doc blocks outside vimscript files

For some plugins, there's no natural place to put doc comments like @section blocks to control vimdoc output, so we've resorted to a convention of adding empty plugin/doc.vim files purely to contain the doc comments. This is a little unintuitive and adds unnecessary runtime overhead.

We should investigate an alternative mechanism to define doc sections in a separate non-vimscript file.

Support per-buffer settings

Vimdoc should be able to document buffer-local variables users can set to control plugin behavior on a buffer-by-buffer basis.

These per-buffer settings typically don't have a centrally-defined value with a let line. Usually they'll just be accessed via an exists('b:myplugin_somevar') or get(b:, 'myplugin_somevar', g:myplugin_somevar) somewhere in the code, so we'll probably need to support declaring them explicitly with a @setting NAME block directive that works like @function ... and @command ..., which will also be useful for #57.

We'll need to fix a few places throughout the code that assume "g:" scope, like whatever is adding the extra "g:" prefixes from #18.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.