[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: overriding the filter method





"Etienne M. Gagnon" wrote:

> Steve Kelem wrote:
> >
> > The TKeyword method looks useful and needs to be documented better. I see (on page 35) that
> root.node.TSomeToken is generated by the Lexer, but it's not until page 62 that you mention get/setLine
> (but not get/setColumn). Even though the method is mentioned, there doesn't appear to be a description of
> what arguments are needed for the TSomeToken constructor.
>
> Why don't you simply generate the framework, then look at the source code of:
> .../node/TKeyword.java
> .../node/Token.java
> .../node/Node.java

Why not? Because I'm starting bottom-up, writing and (I hope) creating regression tests for the lexer.

Reverse-engineering code (which is what it sounds like you're suggesting I do) is useful to find out (1)
WHAT is being done by the code, but almost useless to find out (2) WHY it's being done, or, more
importantly, (3) WHAT NEEDS TO BE DONE to get new code to work. (Caps to emphasize the three different
aspects of understanding code, not to raise the volume.) To build on someone else's work, one shouldn't have
to understand ALL the details, only the ones necessary to build new applications, namely, the interface
details.

> The code for get/setLine is quite easy to understand. (You don't need a thesis to understand them...
> [joke];-)

I was referring to the details of the constructor. If one wrote documentation for the constructor that was
something like:

line number--the line number
column number -- the column number

That wouldn't tell the user much about how to use the constructor. It would be more useful if it would say
something like
line number -- the line number in the source code of the token that was just read
column number -- the column number of the first character of the token just read.
The token uses this information to ...


> By looking at the source code, (and using Javadoc to document "public/protected" methods) you can get a
> pretty good idea of how the AST is encoded, as well as discover methods/constructors available to you.  DO
> not generate documentation for package/private members though:  these change sometimes for SableCC version
> to version.
>
> Etienne

Steve

begin:vcard 
n:Kelem;Steve
tel;fax:408-399-8905
tel;work:408-335-2718
x-mozilla-html:FALSE
url:http://www.adaptivesilicon.com
org:Adaptive Silicon, Inc.
adr:;;985 University Ave., Suite 31;Los Gatos;CA;95032-7639;U.S.
version:2.1
email;internet:kelem@adaptivesilicon.com
title:Chief Scientist
fn:Steve Kelem
end:vcard