[mini.doc] `---@module` is included in automated documentation strangely

Contributing guidelines

[X] I have read CONTRIBUTING.md
[X] I have read CODE_OF_CONDUCT.md
[X] I have updated 'mini.nvim' to latest version

Module(s)

mini.doc

Description

A lua file such as

--- *my_module*
---
--- Some module with text!
---
---@module 'my_module'

local M = {}

--- Do something.
---@param value string Some text.
---@return number? # A value.
function M.to_number(value)
    return tonumber(value)
end

return M

Ends up looking this this

==============================================================================
------------------------------------------------------------------------------
*my_module*

Some module with text!

'my_module'

------------------------------------------------------------------------------
                                                                 *M.to_number()*
                             `M.to_number`({value})
Do something.
Parameters ~
{value} `(string)` Some text.
Return ~
`(number)` `(optional)` # A value.

 vim:tw=78:ts=8:noet:ft=help:norl:

The documentation of mini.doc recommends *Foo* syntax for defining module names (which does syntax-highlight in vimdocs as expected) so I see this extra 'my_module' as an unintended extra. It'd be nice to have mini.doc ignore these ---@module 'foo.' lines and incorporate them more holistically (see https://github.com/echasnovski/mini.nvim/issues/1227 for details)

Neovim version

NVIM v0.11.0-dev-345+g3e6cec0be

Steps to reproduce

nvim -nu minimal.lua

Open the example file


--- *my_module*
---
--- Some module with text!
---
---@module 'my_module'

local M = {}

--- Do something. ---@param value string Some text. ---@return number? # A value. function M.to_number(value) return tonumber(value) end

return M


3. Call `:lua require("mini.doc").generate({vim.fn.expand("%:p")}, "/tmp/out2.txt", {})`
4. View the resulting `"/tmp/out2.txt"` file

### Expected behavior

The line that contains `---@module 'foo.bar.fizz.buzz'` is not rendered in the output. And possibly the newlines leading up to it removed as well unless there's non-whitespace comment lines after it. Basically pretend it isn't there.

### Actual behavior

The `@module` annotation gets stripped and its remaining text is accidentally in the output.

Thanks for the issue!

This works as expected. The reason this happens is because @module annotation does not have a recognized section hook. It means that this is not recognized as a separate section, but as a continuation of the previously detected section (in the example above it is all the text from the start of the block which has default section id, i.e. @text).

To process @module attribute as a separate section, I'd suggest the following:

Create a file 'scripts/minidoc.lua' in the project root.

Put the following lines there:

if _G.MiniDoc == nil then require('mini.doc').setup() end
local hooks = vim.deepcopy(MiniDoc.default_hooks)
hooks.sections['@module'] = function(s) s:clear_lines() end
MiniDoc.generate(nil, nil, { hooks = hooks })

Closing as currently working as expected and might be resolved as part of #1227.

echasnovski / mini.nvim