search

Raku / doc

🦋 Raku documentation
https://docs.raku.org/
Artistic License 2.0
285 stars 293 forks source link

type-graph.txt: what is it good for? #2584

Open JJ opened 5 years ago

JJ commented 5 years ago

The problem

type-graph.txt was created 7 years ago as a

human- and computer-parseable map of Perl6's type graph

From them on, it's outdated both ways and I don't really see the need for it, since there's introspection both into the classes and into the roles (although there might be some problem with NQP roles, it's not unsurmountable, I think).

Suggestions

As part of the redesign of the documentation system #2542 (see also this), we should consider getting rid of it and populate Perl6::Type (#2573) by using the metamodel entirely.

finanalyst commented 5 years ago

Whilst I find the Type Graphs in the documentation to be pretty, I have never found them useful. I could not work out what to do with them. However, I could see a use for them.

If I could trace in which class some function come, eg. is lc defined in Str or Cool or Mu (I am not trying to be correct here, just illustrative. If this could be done by hovering the mouse over a Type diagram, it would be useful.

Also I have found that some graphs are so small as to be almost meaningless, whilst others are so large that it is difficult to read everything.

My suggestion is to eliminate the TypeGraphs from the documentation system until a better way of achieving the aim of increasing clarity has been demonstrated.

AlexDaniel commented 5 years ago

I use them.

For example: “uhhh, what was that role related to numbers?”. Boom:

image

OK, Real and Numeric. Very clear.

JJ commented 5 years ago

While including graphs or not would be a worthwhile debate, let's try and stick to the point, which is the fact that we are using an external file for metadata that can actually found by introspecting the class itself.

moritz commented 5 years ago

I think one of the original reasons not to use introspection was that we might want to hide some details from the users, like for example NQPMatchRole that is mixed into Match.

If we switch to introspection, we need at least some form of customization for it. If we have that, I have no problem with getting rid of it.

JJ commented 5 years ago

@moritz we could achieve that with on-line blacklists instead of an off-line whitelist; that is, customization as you say.

JJ commented 5 years ago

This is included now in the document metadata proposal