Chapel: Likely unwanted symbols (with no apparent source) appearing in documentation

[ian-bertolacci]

I found these strange symbols (domain.forwarding_expr7__value, array.forwarding_expr8__value in the Chapel Domains and Arrays documentation.

Oddly, a complete search of the chapel source does not bring up this symbol.
There are likely others.

[mppf]

I suspect that it would be appropriate for chpldoc to ignore symbols marked with FLAG_COMPILER_GENERATED.

[daviditen]

The symbols you found are coming from forwarding expressions. For example, the domain one is here.

I agree that they should should be ignored in the documentation.

[bradcray]

I can't tell if anyone has taken ownership of this issue, but it looks like it should be as simple as updating this test in symbol.cpp:

// Don't generate documentation for this symbol, either because it is private,  
// or because the symbol should not be documented independent of privacy        
bool Symbol::noDocGen() const {
  return hasFlag(FLAG_NO_DOC) || hasFlag(FLAG_PRIVATE);
}

[lydia-duncan]

I think this is more complicated - I suspect that we want to document methods and such that we get due to forwarding (and that we probably want to hide that we get them from forwarding). I would make a new check in documentation that goes through the information provided due to forwarding after the normal methods and fields defined on the type

[lydia-duncan]

To rephrase - we shouldn't say domain.forwarding_expr7__value but should trigger the generation of documentation for symbols we get because of forwarding based on its presence

[lydia-duncan]

I have traditionally owned documentation related things and would be happy to add this to my next sprint if we thought it was worth prioritizing alongside my other work

[bradcray]

What if we thought of this as two steps: (1) stop documenting bogus/internal/compiler-generaetd symbols poorly (should be easy), (2) add documentation for forwarded symbols (probably more work)?

[lydia-duncan]

Yes, but I think a solution that handled both at the same time would look different from solving them individually, and would either spread out the notion of what forwarding should mean within our documentation pass (as opposed to keeping them close together) or completely remove the easier solution once we got around to the harder one

[lydia-duncan]

That's not to say that we shouldn't follow what you're describing (removing the easy solution should be really simple, I'm just worried we'd forget it was there), just pointing out the tradeoffs

[mppf]

In the particular case, because the field forwarded to is generic, I don't think it's really useful to try to document the methods available there, because the compiler won't know that just looking at the _array declaration. And, in fact, the set of methods available will vary with the type of array.

Since it won't help in this case, it makes me wonder if documenting the forwarded symbols is really useful in general - or if the goal should merely be to note that the type uses forwarding to another type (somehow).

[lydia-duncan]

n the particular case, because the field forwarded to is generic, I don't think it's really useful to try to document the methods available there, because the compiler won't know that just looking at the _array declaration. And, in fact, the set of methods available will vary with the type of array.

Since it won't help in this case, it makes me wonder if documenting the forwarded symbols is really useful in general - or if the goal should merely be to note that the type uses forwarding to another type (somehow).

I think that's an argument against documenting forwarded methods from fully generic fields, rather than against documenting forwarded methods. I expect most use cases for forwarding would want to have documentation for all the operations you can do on the type because of forwarding (if it's important enough to allow it to be treated like a method on a type rather than a method on a field of the type, it's important enough to document).

I think the fact that these methods are obtained via forwarding is an implementation detail that should be hidden from the user of the type.

[lydia-duncan]

I opened an issue to discuss documenting forwarded methods (#9801)