Document a bit more of the metamodel.

[cfa]

Add brief pages on Metamodel::ModuleHOW and Metamodel::PackageHOWand document their roles.

A couple of the roles included here are stubbed; they're included so that the newly added pages are properly cross referenced but would benefit from expansion, further examples.

RfC: @moritz, @niner, @ugexe.

[moritz]

I'm not a fan of listing methods without actually documenting them. Then people find them in the search, click on it... and learn absolutely nothing. Better to let them know right in the search that there is no documentation for it yet.

[cfa]

Makes sense (this is one of the roles that I was referring to in the description re: "stubbed").

We could change this to a one liner (as I have in ModuleHOW) to say something like: "Metamodel::MethodDelegation declares delegate_methods_to, delegating_methods_to and find_method (currently undocumented)."

At least that way there's some discoverability?

[zoffixznet]

This appears to document things that aren't part of Perl 6 language:

~/R/rakudo/t/spec (master)$ grep -FIRn pretend_to_be .                                                                                                                                                                              
~/R/rakudo/t/spec (master)$ grep -FIRn delegate_methods_to .                                                                                                                                                                        
~/R/rakudo/t/spec (master)$ grep -FIRn pretend_to_be .
~/R/rakudo/t/spec (master)$ 

What's implemented in Rakudo is largely irrelevant; it's merely an implementation. The language is defined by the specification and at least three methods being documented here aren't even mentioned in it.

[cfa]

@zoffixznet is TypePretense the only case of that, or are other roles here unspecced?

[Edit: oh, I see you have an example from MethodDelegation too.]

Suggestions on what to include then? It's rather difficult documenting the meta model in a partial way.

[zoffixznet]

Suggestions on what to include then?

Grep the spec and see if there are any tests specifying the behaviour of the feature. The stuff that's specced can be documented. The rest needs a design decision and spec tests to cover the feature.

[cfa]

There's very little here that meets those criteria. Versioning seems to be specced for ver and auth (but not set_*); type_check and find_method can probably be documented too, though I need to dig into roast a little more to see whether those are the role methods.

I'm not sure how worthwhile it is to document the meta model in such a sparse and incomplete way, though; should this just be dropped?

[zoffixznet]

We could leave the PR open until the stuff is specced.

You could open an Issue in roast, mentioning what methods aren't specced. Then people who are familiar with the design of the meta model can say which methods are meant to be part of the spec and which are just Rakudo's implementation detail. From then, it should be fairly easy to write the spec tests for the stuff that needs to be specced and then the PR documenting that stuff can go in.

[cfa]

SGTM. I'll draft something this afternoon.

Thanks @zoffixznet.

[coke]

FYI, this PR fails two tests:

xt/examples-compilation.t - doc/Type/Metamodel/Versioning.pod6 -- looks like declaring a variable might solve this issue.
xt/aspell.t - Looks like the majority of these are type names that need to be added to xt/words, but ("checkee" is slightly wonky, but comes directly from the rakudo source, so that's fine to add as well)

[cfa]

@coke thanks; rebased the original commit onto the latest master, addressed the issues you raised in c86f9ef. (Not sure why shippable's failing.)

Frankly, though, I'm tempted to just close this PR and revisit the issue once everything's specced.

[JJ]

Shippable is failing... A lot. For the time being, just pay no attention to it.

[JJ]

It would be interesting to take a look at this now. Some of the stuff might be already specced, and anyway you have to update your copy due to the conflicts with xt/words.pws...

[JJ]

As with the rest of the NOTSPECCED documents and methods, I think it's better if it's very clear that they are part of the implementation, and documented as such. Would you please update these pages to include that?