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

[ColinKennedy]

Contributing guidelines

• I have read CONTRIBUTING.md
• I have read CODE_OF_CONDUCT.md
• I have updated 'mini.nvim' to latest version

Module(s)

mini.doc

Description

Related to #1227

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 #1227 for details)

Neovim version

NVIM v0.11.0-dev-345+g3e6cec0be

Steps to reproduce

1. nvim -nu minimal.lua
2. 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.

[echasnovski]

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.