> a solution that requires no additional syntax. That's where I'm not so sure. There are two types of out-of-proc doc comments. Those with a module scope that constitute the header of the documentation, and those for the overloaded proc sections. First, the documentation generator has to sort out these two types of comments and I'm not sure that position in code is a good criteria.
The rule for proc's documentation comment is that it applies after the proc it documents. With the section comments it would be before. This rule is acceptable. But the section comment would require the author to group all overloaded proc after the comment. This constraint seems to be too much strong. Sometimes you want to write procs after the main type the apply to, sometimes you follow other rules... I'm not a reST expert, but I think that sections for overloaded proc should have a [reference](http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role) to refere to the group of overloaded procs it relates, like in the example below: ## _`+` ## Addition on matrices and vectors. ## --------------------------------- ## Addition adds each item of the first matrix or vector to the ... ## _`$` ## String representation ## --------------------- ## Matrices and vectors are converted to string with the ``$`` operator. ... This reST syntax would disambiguate for the documentation generator. Else these comment blocks are part of the general header and go to the top of the documentation. If there's no better idea, I'll try to implement it in the documentation generator. \-- Pierre
