Documenting attributes

[Malte Schwerhoff]

Dear list,

what's best practice when it comes to documenting attributes in the
source code (maybe even utilising ScalaDoc)?

What I have in mind is a kind of documentation that lists all available
attributes for a given node (hence the reference to ScalaDoc). However,
the attributes are usually not known at node side already, but if the
attributes are documented as just regular methods then there isn't a
single place that lists all attributes available for a certain node.

And something slightly related: has anyone experimented with IDE support
for attributes, e.g. code hints/autocompletion?
I wonder whether using the Pimp My Library pattern to "turn" the
node->attr syntax into node.attr would facilitate IDE support, and how
big the runtime penalty is.

Cheers,
Malte

[Tony Sloane]

Dear Malte,

> what's best practice when it comes to documenting attributes in the
> source code (maybe even utilising ScalaDoc)?
>
> What I have in mind is a kind of documentation that lists all available
> attributes for a given node (hence the reference to ScalaDoc). However,
> the attributes are usually not known at node side already, but if the
> attributes are documented as just regular methods then there isn't a
> single place that lists all attributes available for a certain node.

I'm not sure there is any best practice for this sort of thing yet. To
my mind attributes are functional in the sense that they are associated
with a type (say Expression) rather than a particular sub-type of that
type (say AdditionExpression).

I see your point though. How does someone find out about expression
attributes when they are looking at the documentation for a particular
kind of expression?

I suppose there is nothing stopping you adding such documentation to
the AdditionExpression class documentation, referring to the module
in which the attributes are defined. That would lead to duplication in
the docs of each sub-class of Expression. Alternatively, you could
document them in Expression with a short pointer from sub-classes.

A counter argument to all of this is that attributes are intended to
be separate from the classes on which they operate. Therefore I can
come along at any time and add new attributes to existing classes
without having to modify those classes. Adding attribute documentation
to the classes couples them more closely than you may want.

> And something slightly related: has anyone experimented with IDE support
> for attributes, e.g. code hints/autocompletion?
> I wonder whether using the Pimp My Library pattern to "turn" the
> node->attr syntax into node.attr would facilitate IDE support, and how
> big the runtime penalty is.

I'm not currently using an IDE for my Scala work, so I haven't tried
this sort of thing and I'm not aware of anyone else who has. I think you
could do it, but that pattern does incur some object creation overhead.
I've seen claims that the JVM can remove it easily since the objects
are very short-lived, but I haven't measured.

cheers,
Tony

[Malte Schwerhoff]

Dear Tony,

I agree, I'd also prefer not having to explicitly reference attributes from the documentation of nodes, and rather have the documentation tool compile a list of available attributes for a given node by looking at the type of the attribute function. I have no experience with ScalaDoc, but I imagine that it is possible to extend it in such a way that it compiles the desired attribute list. I'll try to find some time to have a look at ScalaDoc and search the mailing list for related posts.

 

> And something slightly related: has anyone experimented with IDE support
> for attributes, e.g. code hints/autocompletion?
> I wonder whether using the Pimp My Library pattern to "turn" the
> node->attr syntax into node.attr would facilitate IDE support, and how
> big the runtime penalty is.

I'm not currently using an IDE for my Scala work, so I haven't tried
this sort of thing and I'm not aware of anyone else who has. I think you
could do it, but that pattern does incur some object creation overhead.
I've seen claims that the JVM can remove it easily since the objects
are very short-lived, but I haven't measured.

I've heard the same claims, and I am also not (yet) using an IDE for developing Scala programs, simply because the experiences I made so far where not really ... overwhelming. However, rumor has it that the IntelliJ's support for Scala has reached a decent level, and I wouldn't mind having autocompletion etc. for my Scala projects. Once my Kiama toy project is "stable" I'll experiment a bit with the Pimp My Library pattern and run some benchmarks

Thanks for your great work!

Malte