Access message documentation in Smalltalk

Question

When you define a class in Smalltalk, you can acces the documentation comment like this:

st> Integer comment
'I am the abstract integer class of the GNU Smalltalk system.  My
subclasses'' instances can represent signed integers of various
sizes (a subclass is picked according to the size), with varying
efficiency.'

But maybe, I'm to newbie to Smalltalk, but I cannot find how to access to the method/message documentation. i.e.

Method comments, if present, are inlined in the method's body, usually right below the signature. Therefore, to get them you should parse the method yourself or get the parse tree (a.k.a. ast) and look for comment nodes. — Leandro Caniglia, Aug 20 '18 at 16:45
You want to have something like RDoc? Well some implementations (e.g. Smalltalk/X) have example attached for the usage of that Class. In Gnu-smalltalk I think it is easier to check the documentation on web. For base: https://www.gnu.org/software/smalltalk/manual-base/gst-base.html; for libs: https://www.gnu.org/software/smalltalk/manual-libs/gst-libs.html — tukan, Aug 21 '18 at 08:55

Leandro Caniglia · Accepted Answer · 2018-08-22T21:13:32.663

Let's consider the following method

SomeClass >> #msg: arg
  "This is a comment"
  ^self doThisTo: arg

It is tempting to implement a service for extracting comments such as:

commentOf: aCompiledMethod
  ^method sourceCode readStream upTo: $"; upTo: $"

In fact, in the example above, we would get the string 'This is a comment'. The problem, however, is that the double quote character is not always a comment delimiter. Consider for instance the following method

String >> #doubleQuoted
  ^'"', self , '"'

if we tried to use our method #commentOf: above for extracting comments from this method, we would get

' , self, '

which doesn't make any sense.

This means that our parsing should be less naïve. Therefore, the question that we should ask ourselves is whether it is not better to use the Smalltalk Parser of our environment. I don't know how to do this in gnu-smalltalk, so let me show here (as an example) how could we proceed in Pharo:

aCompiledMethod ast comments

The #ast message answers with the Abstract Syntactic Tree of the the method, also known as the Parse Tree, which exposes the syntactic structure of the method's source code. In particular, it detects all comments in the form of CommentNode objects, and that is why the #comments method simply consists in enumerating all parse nodes while collecting the comments.

Access message documentation in Smalltalk

1 Answers1