Should we provide a specific way to document attributes?

[e-kayrakli]

I'll start with context. We had assertOnGpu() standalone function that was documented in the GPU module docs. We deprecated that in favor of @assertOnGpu attribute on the loop. So, now, how can we document the new attribute? In the short term, I don't think it is a big deal to add a header under GPU technote.

In general, should there be some special support for documenting attributes in chpldoc? While sticking something in a module code can be appealing and approachable as it can be similar to what we have been doing, it seems wrong. Attributes are a compiler/tool concept. So, attributes that we have should be documented in the compiler code where we "define" them. But how?

Another question about this is how it should be rendered. An easy solution is to have an attribute index where we list every documented attribute. But it is also appealing to drop in attribute documentation into other rst files. For example, it would be great if the assertOnGpu documentation was in the GPU technote. If the same thing was redundantly in the attribute index, that wouldn't bother me. But maybe we can keep the index as just list of links where attributes are documented in related places like in spec, relevant module docs, or technotes.

Arguably, there should be a style that can set aside attributes from other things we're documenting today.

[lydia-duncan]

I recommend two strategies (combined):

1. A page dedicated to attributes we support. This probably should go in the spec? Or in the documentation of the feature it is most relevant to?
2. chpldoc documentation rules if/when we allow user-defined attributes.

[DanilaFe]

I am interested in prototyping this. I actually think that we can do this using procedures. Since Chapel attributes support actuals, and have names, I think we can create special 'attribute procedures', which are excluded from function resolution (perhaps they implicitly have a where false block) and are named the same thing as an attribute.

/** This attribute does bla bla bla... */
@attribute
proc assertOnGpu /* where false? */ {}

/** This attribute does bla bla bla */
@attribute(namespace="gpu")
proc blockSize(size: integral) {}

This:

• Makes it easy to mark where we want documentation for attributes to show up
• Allows users to document their custom attributes in a similar way
• Has the added support for documenting attribute formals

[lydia-duncan]

You had me until "allows users to document their custom attributes in a similar way".

We haven't finalized the syntax for (or even if we want to support) custom attributes, and the only way to add an attribute today is to modify the compiler, so far as I know. Therefore I think we should hide any thing that might bleed implementation details and imply that users can define their own until it is actually possible for them to do so - this will avoid getting user questions about "why isn't this working, I wrote it like the docs". It will also allow us to transition from this shortcut to support that reflects the true complexity of the feature when custom attributes are possible.

[lydia-duncan]

That said, I think what you've proposed is an excellent way to get support ready quickly, and I would be interested in being present in a meeting to brainstorm what exactly the output should look like

[DanilaFe]

When I said "user provided custom attributes" I meant tool attributes -- and I thought we have already "added support for it", in that we can pass a flag to the compiler to allow certain toolspaced attributes. Either way, we could disallow the @attribute annotation (or pragma) from being used outside of module code.

[lydia-duncan]

Ooooh, I see. You mean for things that are recognized and responded to in programs outside of the Chapel compiler. And it makes sense that those would not be scenarios where a user is as likely to see an example and try it in a way that would frustrate them. I buy that.