Cannot add functions to a documented section.

[NicolBolas]

trafficstars

According to the documentation on Sections, a @section command has a domain that extends until the next @section block (with @section end being a special end tag that reverts to normal.

Also, @within is supposed to be able to add functions to sections arbitrarily. From the documentation:

This allows you to put adjacent functions in different sections, so that you are not forced to order your code in a particular way.

OK, so with @within, ordering of functions is no longer relevant.

But there are a couple of problems here.

Problem 1: Once you end a section, you cannot start it up again. A new @section declaration with the same name will be treated as a new section.

--[=[--
A testing module.
@module test
]=]

--[=[--
First section
@section section_1
]=]

--[=[--
Function
]=]
function func1 () end

--[=[--
@section end
]=]


--[=[--
Function
]=]
function func2 () end

--[=[--
@section section_1
]=]

--[=[--
Function
@within section_1
]=]
function func3 () end

This makes section names rather pointless.

Problem 2: @within cannot add a function to an existing section:

--[=[--
A testing module.
@module test
]=]

--[=[--
First section
@section section_1
]=]

--[=[--
Function
]=]
function func1 () end

--[=[--
@section end
]=]


--[=[--
Function
]=]
function func2 () end

--[=[--
Function
@within section_1
]=]
function func3 () end

This results in three sections, not two. func3 will be in a section named section_1. So apparently @within has a different namespace from @section. I presume there is a distinction between so-called "implicit sections" and "explicit sections".

Fortunately, @within doesn't care about function order. The problem is that the "implicit sections" @within creates cannot have their own documentation. You can give them a more descriptive title, but nothing more than that.

If the intent is that you cannot add functions out-of-order to documented sections, then the documentation ought to spell this out in greater detail. If this is not the intent, then it is a bug that should be fixed.

[alerque]

This issue has significant overlap with #262, but isn't quite a duplicate.