|
|
|---|
|
|
|
|---|
Representation of comments within a top-level design elements.
We might try to leave comments in the token stream and then try to preserve them as we parse by attaching them to various parse-tree structures. But since comments can occur anywhere, this would really complicate how parsing is done and would also be bothersome to our transformations, where we would need to worry about when comments are present and whether they should be copied, etc.
On the other hand, we do not want to just throw all the comments away. They might be valuable to a human who is trying to read and understand the translated source code, and we really want the translated code to be as readable, complete, and helpful as possible to the verification person who is trying to work on it.
So, rather than throw comments away, our loading functions set them aside into a comment map, which is an alist that maps vl-location-p objects to strings.
By construction, each of these strings is known to be a valid Verilog
comment, i.e., it begins with
BOZO this comment applies to the behavior of
When I originally developed the comment map, I imagined associating every comment with its exact starting location in the file, hoping that this would allow me to recreate the comments after transforming the module. But my new approach is to say that every comment begins at Column 0, regardless of where it actually occurs in the line.
Why? First, let me identify three commenting styles:
Style 1:
/* the following decodes the controller signal from the such-and-so unit. the valid values are blah blah blah blah ... */ wire ctrl_sig = ~w[0] & ...;
Style 2:
// decode controller signal from such-and-so unit wire ctrl_sig = ~w[0] & ...;
Style 3:
wire ctrl_sig = ~w[0] & ...; // decode controller signal
If we record the exact positions of the comments, then we get perfectly good behavior when Styles 1 and Styles 2 are used. However, we get a very BAD behavior for comments of Style 3. In particular, the translation of ctrl_sig will be some litany of wire declarations and gate/module instances, which are all said to be at Line L on column C. However, this comment will be at Line L on Column C+X. The net result is that the translation will look something like:
wire ctrl_sig; } wire _gen_37; } Line L, Col C wire _gen_38; } buf(_gen_37, w[0]); } ... } and(ctrl_sig, _gen_38, _gen_39); } // decode controller signal } Line L, Col C+X
Having the comment come after this big mess of stuff is really unfortunate, and, even worse, it makes it look like the comment refers to whatever comes NEXT. This could lead the reader to think that comments are about wires which they are not, and is really bad.
So, instead, I now switch all comments to use Column 0. We have taken great care in the writer to ensure that (1) the mergesort is stable, and (2) comments are given before module items, so that this approach essentially forces all comments to act as though they occur at the start of their line.
The current approach is pretty bad w.r.t. internal comments, e.g., if I
write an expression with lots of