[documentation] some expanded documentation types are invalid pony-code

[mfelsche]

What i was trying to achieve

I wanted to write a method which accepts everything a Set would accept. I copy and pasted the type parameter As signature into my method.

Code with bug

use "collections"

actor Main
  new create(env: Env) =>
    let singleton = singleton_set[String]("A")

  fun singleton_set[A: (Hashable #read & Equatable[A #read] #read)](t: A)
    : Set[A] 
  =>
   Set[A](1) .> add(t)

http://playground.ponylang.org/?gist=7b903395cd00e4840d185be3761eba60

Actual Result

0.17.0 [release]
compiled with: llvm 3.9.1 -- cc (Ubuntu 5.4.0-6ubuntu1~16.04.4) 5.4.0 20160609
Error:
main.pony:5:54: a capability set can only appear in a type constraint
  fun singleton_set[T: (Hashable #read & Equatable[A #read] #read)](t: T)

Expected Result

I would expect the type signatures in the autogenerated pony documentation to be valid pony code.

The actual definition of Set is:

type Set[A: (Hashable #read & Equatable[A] #read)] is HashSet[A, HashEq[A]]

The documentation signature is:

type Set[A: (Hashable #read & Equatable[A #read] #read)] is
  HashSet[A #read, HashEq[A #read] val] ref

After discussing this with @SeanTAllen it is clear that the docgen process needs expanded types in order to establish the links between classes and traits etc.
It would really help if the actual signature was the real code representation of the type/class/actor definition. The expanded form should also stay available.

Is there already a link from the ast_t of the type (class/actor/trait) definition to its textual representation?

[jemc]

For whatever it's worth, when this came up in IRC I was of the opinion that showing invalid Pony syntax for the trait signature of the type is a documentation bug.

Is there already a link from the ast_t of the type (class/actor/trait) definition to its textual representation?

If I recall correctly, it links to the position of the start of the text, but I don't think you necessarily get the length, which you would need.

---

However, I think there is an easier way to solve this. When printing the type in docgen, you should be able to add logic to print the cap for a type, only if the following conditions are met:

    if((ast_id(type) != TK_TYPEPARAMREF) ||
      (opt->check.frame->constraint != NULL) ||
      (opt->check.frame->iftype_constraint != NULL))

In other words, don't print the type's cap if it is a type param ref outside of a constraint context.

[plietar]

Type params don't allow refcap in any context, even in constraints.

[jemc]

Right, thanks @plietar.

[jemc]

This should be fixed by #2184.