Methods, routines, subs mislabeled in classes Mu & Any

[finanalyst]

@coke @lizmat
Using search for 'isa', select in category 'Heading', takes you to class Mu
Note that the heading is 'routine', but the definition in code section is only for 'method'. Using isa(Any) generates Undeclared routine.

After thinking how it could be otherwise, this seems reasonable.

But documentation seems wrong: other headings in Mu are mixed 'method' and 'routine', so suggest changing 'routine' in heading to 'routine'.

Same is true for 'does'.

I've not raised a PR for the changes because

1. Not sure there was some other documentation intention originally
2. Perhaps documentation could be added by giving example of &isa with invocant ?
3. How many more of these mismatches exist

I can make changes to isa and does after feedback about above.

[coke]

As I understand, if there are only methods or only subs, then we use that as the heading as well, and if there are both, we use 'routine'. I think that the signature test (which is mostly disabled at this point) would be the place to verify if we have one or both, and therefore if the heading is correct.

[finanalyst]

@coke In the two examples I cited, there are no sub forms documented, and trying to use one generates an error.

I thought there was a way to turn a method to a sub using an explicit invocant (for option 2). I seem to have misremembered something. So ignore option 2.

[raiph]

Interesting coincidence. I feel I should write a couple comments.

I was just reading https://github.com/Raku/doc/blob/main/writing-docs/INDEXING.md as part of an attempt to do as @tbrowder prompted here.

One of several things that threw me was this sentence:

Other than explicit creation, headers (=head elements of Pod) of certain format get an anchor automatically, say =head routine sin creates an index item categorized as Subroutines automatically.

I thought to myself that "If that's true, it's wrong and should be fixed. If it's false this 'how to contribute to the doc doc' should be fixed."

A few seconds later I saw this issue listed and thought "Hmm. That might be about the very same issue, or a related one, given its title." So I clicked. Now I'm here it really does seem to be related.

That prompted me to write this comment.

[raiph]

@finanalyst

suggest changing 'routine' in heading to 'routine'.

Not sure that'd help. 😁

[arkiuat]

So if I understand @coke correctly, if both a sub and a method of the same name exist, they should be documented together in a unified entry headed 'routine'; if a sub or a method only, then in an entry headed 'sub' or 'method' accordingly. In the docs, sometimes a sub and a method are listed side by side in separate entries: I think that this makes it more difficult for the reader to perceive the logic of the section-heading scheme (it certainly did so for me).

@finanalyst pointed out that in class Mu, the methods isa and does are listed as routines. Furthermore:

The sub take-rw is listed as a routine.

The routines take and defined have separate entries for sub and method, and should each be unified into a single routine listing. In both these cases the sub entry is incorrectly labeled routine, sitting right next to the method entry.

print, put, say, return, return-rw, emit, so, and not are listed only as methods, but should be listed as routines. There are probably more of these. Each of these also has an entry in Type/independent-routines.rakudoc as well but I still think the section headings should be consistent about the actual current status of each of these.

All of this is just for class Mu. I'm tempted to do a systematic search (probably with a script) for instances of these kinds throughout the Type/ directory, but I might just correct the entries in class Mu first if that would be welcome.

I know not everyone may prioritize consistency in these practices the way I do, and there may be some reasons for things being this way that I'm not aware of, but @finanalyst implicitly raised that same question over half a year ago and I don't see any such reasons indicated in the replies.

[coke]

Sounds good - if we can set a good example in Mu, we can apply that to the rest of the types as well.

As noted earlier, there’s a test that this could be added to, but it would also be fine to add a new one (there are probably a few you could base it on). Good luck!

[arkiuat]

I submitted draft PR #4668 to correct the section titles in Mu I identified, as the low-hanging fruit, but there are three links that util/test-modified.sh says my changes break

under does: L<C<isa>|/routine/isa#(Mu)_routine_isa>
under isa: L<C<does>|/routine/does#(Mu)_routine_does>
under return-rw: L<C<return>|/type/Mu#method_return>

For each of these, I had changed routine to method or vice versa. The original links here go to composite search results and not to a definite page, so I'm guessing that my new links will do similar?

My next step was going to be merging the two take sections and the two defined sections; I'd like to study some examples of other routines that have both sub and method versions but which are documented in a single routine entry before I do so.