Beta-testing 'mini.doc' about mini.nvim HOT 26 CLOSED

* It can be added manually by placing `---` as first line in annotation. Not that pretty, I admit that, but at the moment I feel this is the best solution.

Oh, and also there is another solution: you can implement your own hook for @signature section. It might be used inside of 'minidoc.lua' something like this:

local minidoc = require('mini.doc')
local signature_hook = function(s)
  minidoc.default_hooks.sections['@signature'](s)
  s:insert('')
end

minidoc.generate(nil, nil, { hooks = {
  sections = { ['@signature'] = signature_hook },
} })

from mini.nvim.

@danymat, I've pushed updates for features that come up from this discussion as useful:

• config.annotation_pattern is now config.annotation_extractor allowing for custom annotation indicator. Although, seems like Neogen changed default EmmyLua annotations for Lua to be without space (which I am super happy about, by the way!).
• minidoc_replace_start can support empty replacement.
• @diagnostic and @overload is now a thing.
• And finally, there is a possibility of automatic table of contents: insert @toc_entry inside block from which tag should be taken and insert @toc where you want to render TOC. For more information see 'mini.nvim' documentation and source code (final result and some @toc_entry).

Thanks again for your insights and congratulations on increased, fully deserved recognition of Neogen.

from mini.nvim.

Thank you all for beta-testing 'mini.doc'! I made new release, so it is now not in beta any more.

from mini.nvim.

Hello, I'm beta testing this module and trying to replace the docgen currently in place in Neogen.

I tried generating the files and it works wonderfully !
I was considering, how could I provide a set of ordered files in my plugin, in order to build the file ?

In the docs, it's written:

- `Doc structure` is an array of files describing a final help file. Each
  string line from section (when traversed in depth-first fashion) goes
  directly into output file.

from mini.nvim.

Thanks for trying it out!

Current approach is to supply it in input argument of generate(). Either:

• Manually inside of command line call (like :lua MiniDoc.generate({'lua/mini/init.lua', 'lua/mini/doc.lua'}, 'doc/mini.txt')).
• Automatically by creating a 'scripts/minidoc.lua' script with call to MiniDoc.generate() and then manually calling MiniDoc.generate() again. For more details see documentation of MiniDoc.generate().

from mini.nvim.

Thanks for you quick answer ! I'm trying out second option and it works well. By the way, i could ask for a feature request: adding a TOC on top of the doc. I think this is quite mandatory for a plugin, and it should take every tag in the file and generate the pretty TOC we see on most plugins

What do you think ?

from mini.nvim.

One more question: is it possible to skip a certain annotation ?
For example, sumneko language server require --- before @diagnostic, like this:

---@diagnostic disable-next-line: lowercase-global
neogen = {}

But doing this, it's treating this as a doc comment

from mini.nvim.

I would want to generate from this:

To this:

local defaults = {

I don't think living the manioc_replace_start blank is currently treated here

from mini.nvim.

Thank you very much for trying this out! This is very helpful.

Thanks for you quick answer ! I'm trying out second option and it works well. By the way, i could ask for a feature request: adding a TOC on top of the doc. I think this is quite mandatory for a plugin, and it should take every tag in the file and generate the pretty TOC we see on most plugins

What do you think ?

I had this on my list initially, but couldn't resolve many problems with it:

• Customizability:
  • I am sure that not everyone wants every tag to represent TOC entry.
  • The common TOC has two parts: left is a plain text, right is a tag (sometimes skipped). If right part here can be inferred from block (take @tag section), the left one is not so clear.
  • Also the common TOC is not placed directly at the top of the help file, but is preceded by small amount of lines (current Neogen help file is an example here).
    All in all, this means that there should be a way for user to tell what will be placed to TOC.
• Implementation:
  • Current approach is to process files and lines in order. At the time TOC lines should be processed, almost no tags are gathered. I had an idea to allow functions to be an entry for section structure, but it complicates things too much.

All that said, I think I might have an idea of how to do this:

• Add @toc section which will serve as placeholder for where to put TOC.
• Add @toc_entry section which would indicate that this block contributes to TOC. This should allow to somehow customize left and right parts of TOC entry.
• Update default hooks.doc to replace @toc sections with gathered TOC entries.

Does it sound good? I'll think a little bit more about a best way to allow parts customization.

One more question: is it possible to skip a certain annotation ? For example, sumneko language server require --- before @diagnostic, like this:

---@diagnostic disable-next-line: lowercase-global
neogen = {}

But doing this, it's treating this as a doc comment

If you want to not include the whole block, add @private section. If you want to skip sections with certain id, you can implement hook for that section id that removes all lines from its section structure. I'll probably add hook for @diagnostic to ignore its content in output.

I would want to generate from this:

To this:

local defaults = {

I don't think living the manioc_replace_start blank is currently treated here

Yeah, it doesn't :( I found a solution, but it will replace content with empty string resulting into empty line, which seems reasonable. What you might do right now and might even be a better solution is to do this:

--minidoc_replace_start default = {
neogen.setup = function(opts)
  local default = {
  --minidoc_replace_end

from mini.nvim.

Add @toc section which will serve as placeholder for where to put TOC.
Add @toc_entry section which would indicate that this block contributes to TOC. This should allow to somehow customize left and right parts of TOC entry.
Update default hooks.doc to replace @toc sections with gathered TOC entries.

This is a good idea, and looks a lot like the Neorg Table of content syntax, which is: = TOC optional custom name for toc lol !

Thanks for the explanations, I think adding a list of every treated tag and how they're treated (maybe on top of minidoc doc) could be much easier to process.

Some feedback (currently rewriting every doc in Neogen):

• Would it be possible to allow a space between the --- and the tag ? I use Neogen to generate my annotations (😆) and the default annotation, which is emmylua, puts a space between the delimiter and the tag. If not possible, I will have to create a new template for it
• What about adding by default a blank line after the middle content, in a new section ? (e.g between neogen.generate({opts}) and The only...)
  

Certainly more to come, sorry if it bothers you, but I really like this module and I really want to help in improving it

EDIT:

• I just tried to se if @overload was supported, does not seem it is

EDIT2:

Something like this:

Produces this, and we can see that we have the tag, but we do not have a title for the section. I find it quite inconsistent with others

from mini.nvim.

* Would it be possible to allow a space between the `---` and the tag ? I use Neogen to generate my annotations (laughing) and the default annotation, which is emmylua, puts a space between the delimiter and the tag. If not possible, I will have to create a new template for it

I thought about it (in fact, mostly after looking Neogen). Decided to do it like this, because:

• In case of --- @abc Text is @abc a section id or a part of text? If space is not allowed, then it is not ambiguous.
• Both EmmyLua and sumneko language server does not have space. Moreover, sumneko seem to even allow no space for text (but that is also ambiguous). So I am even inclined to be bold here and suggest making this default in Neogen :) .

Nevertheless, I already plan to allow supplying function instead of plain pattern to determine if a line is annotation or not. This way it can be fully customizable to use any rule for detecting annotation comment.

* What about adding by default a blank line after the middle content, in a new section ?

It was a hard debate with myself on this one. I decided to not add blank line mostly for these reasons:

• I prefer (and suggest, really) to use first line as a short description of what function does. This way it creates nice looking "diagonal" path from right tag to first line.
• It really increases line count of help file for a little gain. Not that big of a deal, but 'mini.nvim' already has 3334 lines, with more to come.
• It can be added manually by placing --- as first line in annotation. Not that pretty, I admit that, but at the moment I feel this is the best solution.

Certainly more to come, sorry if it bothers you, but I really like this module and I really want to help in improving it

That is great, thank you! I might be slow to respond during the day, but I'll catch up later.

* I just tried to se if `@overload` was supported, does not seem it is

I am not sure what it should do. What do you expect to be the output of this?

from mini.nvim.

EDIT2:

Something like this: Produces this, and we can see that we have the tag, but we do not have a title for the section. I find it quite inconsistent with others

It has empty line, because:

• First line after block is empty, so there is no inference of tag and signature. Inference is made only if first line is not empty. This allows writing sections which are not related to any object.
• There seems to be empty annotation comment at the start of block. Which is where empty line after tag comes from.

from mini.nvim.

Nevertheless, I already plan to allow supplying function instead of plain pattern to determine if a line is annotation or not. This way it can be fully customizable to use any rule for detecting annotation comment.

This is a very good idea, and would allow more advanced customizations

It was a hard debate with myself on this one. I decided to not add blank line mostly for these reasons:

I see, and I'm okay with this.

I am not sure what it should do. What do you expect to be the output of this?

Hmm.. I think it'll be difficult to use with current implementation. The original idea of overload is to provide a second function signature.
This got me thinking: I think it's not currently possible to create docs just like: :h vim.lsp.buf, is it ? (see that there is the concept of a "module", and functions inside it).

• One more thing: I don't think tags that are still not supported (for example ---@overload) should be treated at all in the doc, and just be skipped. Because at the moment, I'm afraid to change Neogen's default annotation because of this.

from mini.nvim.

Hmm.. I think it'll be difficult to use with current implementation. The original idea of overload is to provide a second function signature.

I can (and probably will) treat it similar to @return: add Overloads~ line and enclose line inside `.

This got me thinking: I think it's not currently possible to create docs just like: :h vim.lsp.buf, is it ? (see that there is the concept of a "module", and functions inside it).

I don't think i follow. If you mean having tag inferred not as hover() but vim.lsp.buf.hover() where vim.lsp.buf is taken from file path, then no, it can't be done easily. However, you still should be able to write custom hook for @tag section. Its input is section structure s, from which you can gather information about current file at s.parent.parent.info.path. And after that decide how to modify tag text: for which files, how deep tag nesting should go, etc.

* One more thing: I don't think tags that are still not supported (for example `---@overload`) should be treated at all in the doc, and just be skipped. Because at the moment, I'm afraid to change Neogen's default annotation because of this.

If they are not supported by default, you can write custom hook to support it :) Inside it can remove all its lines, virtually removing the whole section. But with @overload I think I'll add it (see above).

from mini.nvim.

Hello again,

I set up a GitHub action to use your module, you can see here: https://github.com/danymat/neogen/blob/main/.github/workflows/docgen.yml

If you want to take a look at the newly generated documentation, all the doc is currently processed from lua/neogen/init.lua. I will add more documentation later

I don't think i follow. If you mean having tag inferred not as hover() but vim.lsp.buf.hover() where vim.lsp.buf is taken from file path, then no, it can't be done easily. However, you still should be able to write custom hook for @tag section. Its input is section structure s, from which you can gather information about current file at s.parent.parent.info.path. And after that decide how to modify tag text: for which files, how deep tag nesting should go, etc.

Is it possible to choose which delimiter to use on top of a tag ? (---, ===, nothing,...)

from mini.nvim.

I set up a GitHub action to use your module, you can see here: https://github.com/danymat/neogen/blob/main/.github/workflows/docgen.yml

Very nice! Wanted to do it myself, but didn't have a real need yet. Also want to do a pre-commit hook, when will have more time.

If you want to take a look at the newly generated documentation, all the doc is currently processed from lua/neogen/init.lua. I will add more documentation later

Very nice! What caught an eye: this line swallows first word thinking it is a section id.

Is it possible to choose which delimiter to use on top of a tag ? (---, ===, nothing,...)

Those come from block_post (adds ---) and file (adds ===) hooks. As per current design, you can overwrite those.

from mini.nvim.

Hello ! the toc generation is very useful !
I really like the defaults in mini.doc, and at the moment I haven't used any special customization. I will surely consider it when I start migrating doc files for Neogen development into docgen.

Still using your module, so definitely going to have some feedback missing ! Thanks for the new implementations, they are very useful.

Thanks again for your insights and congratulations on increased, fully deserved recognition of Neogen.

Yes, I'm so happy, but now there's an avalanche of new people and new feedback lol. That means people are using it and want it tailored, which I deeply value.

EDIT: Small bug i found: adding @toc without any toc_entry does generate an error

from mini.nvim.

EDIT: Small bug i found: adding @toc without any toc_entry does generate an error

Thanks! Should be fixed now.

from mini.nvim.

Hi, I just want to report a bug:

Input:

---@alias system.fileinfotype
---|>'"file"'  # It is a file.
---| '"dir"'   # It is a directory.

Output:

------------------------------------------------------------------------------
 # It is a file.
'"dir"'   # It is a directory.

It is possible for alias to not have an afterline1 2. I can't wrap my head around mini.doc and can't solve it.

from mini.nvim.

Hi, I just want to report a bug:

Input:

---@alias system.fileinfotype
---|>'"file"'  # It is a file.
---| '"dir"'   # It is a directory.

Output:

------------------------------------------------------------------------------
 # It is a file.
'"dir"'   # It is a directory.

It is possible for alias to not have an afterline1 2. I can't wrap my head around mini.doc and can't solve it.

Hi, I am not sure what you intend to do here. In current design @alias basically takes first word and registers that it means the rest of the section text. Here is an example. Afterwards, any occurrence of this word will be replaced verbatim with the registered text. Like this annotation will be modified to these help lines

from mini.nvim.

Hi, I just want to report a bug:
Input:

---@alias system.fileinfotype
---|>'"file"'  # It is a file.
---| '"dir"'   # It is a directory.

Output:

------------------------------------------------------------------------------
 # It is a file.
'"dir"'   # It is a directory.

It is possible for alias to not have an afterline1 2. I can't wrap my head around mini.doc and can't solve it.

Hi, I am not sure what you intend to do here. In current design @alias basically takes first word and registers that it means the rest of the section text. Here is an example. Afterwards, any occurrence of this word will be replaced verbatim with the registered text. Like this annotation will be modified to these help lines

Ah, I see. My usecase here is to define a "type" fileinfotype which corresponds to "file" | "dir". A function will later return a fileinfotype value.

Relevant code:

--- including the example I gave before...

---@class system.fileinfo
---@field type system.fileinfotype

---@param name string filename
---@returns system.fileinfo
function system.get_file_info(name) end

Generated output:

------------------------------------------------------------------------------
                                                               *system.fileinfo*
                               `system.fileinfo`

Class~
{system.fileinfo}
Fields~
{public} modified `(number)` A timestamp in seconds.
{public} size `(number)` Size in bytes.
{public} type system.fileinfotype Type of file

------------------------------------------------------------------------------

from mini.nvim.

Again, not completely grasp the use case. My best guess of what is an intention here:

---@alias system.fileinfotype `"file" | "dir"`

---@class system.fileinfo
---@field type system.fileinfotype

---@param name string filename
---@return `system.fileinfo`
function system.get_file_info(name) end

With latest main (I fixed some issues with using . inside alias name) it will produce this:

------------------------------------------------------------------------------
Class~
{system.fileinfo}
Fields~
{type} `"file" | "dir"`

------------------------------------------------------------------------------
                                                        *system.get_file_info()*
                         `system.get_file_info`({name})
Parameters~
{name} `(string)` filename
Return~
`system.fileinfo`

from mini.nvim.

Hello, it seems that the optional param @param test? string is not treated as so, and it outputs:

Maybe we should agree of the ? to show the param as optional, one way of another.

from mini.nvim.

Hello, it seems that the optional param @param test? string is not treated as so, and it outputs:

Maybe we should agree of the ? to show the param as optional, one way of another.

At the moment I am inclined to suggest using |nil as second option (as per alternative convention in sumneko_lua, which it think I saw more often). Although having @param test? string transformed into something like `(optional)` {test} `(string)` or {test} `(string, optional)` would be nice, I have two obstacles to this:

• Current implementation doesn't allow this easily. Mainly because ? can be both in parameter name and returned value, but also because it creates another word.
• This will almost certainly be the reason that line width exceeds 78 characters. Not a very big deal, because this can be solved in annotation comments, but I am not a fan of that.

I'll think about it.

from mini.nvim.

@danymat, I ended up including your suggestion about ?. It is as in sumneko_lua: "Appending a question mark (after the first word)" in @param and @return sections. The @param test? string will be transformed into {test} `(optional)` `(string)` . This needed small code update and is a decent output look in my opinion. Thanks again for practical suggestions!

from mini.nvim.

Hello @echasnovski, I just saw that the latest commit did update, in fact ! This feature is very cool, and I don't need to do ...|nil anymore. Thanks !

danymat/neogen@4c4411c

from mini.nvim.