Guru: Ready or Not! Part 2 of Big Changes in RDi V9.6, Hover and Annotations
April 23, 2018 Susan Gantner
If you’re one of those RDi users who doesn’t bother updating to the latest releases, listen up. I’ll bet that at least one of the new features in V9.6 will entice you to update. In Ready Or Not, Big Changes in RDi V9.6! Part 1, Key Behavior, I covered some RDi key behavior changes. Here I’ll explore some of the more noticeable — and to me anyway, more useful — features: enhanced hover text and new annotation support.
Hover Text
RDi has had hover text for variables and procedures for a while now. You could hover over an item in the source and see the definition of that variable. Figure 1 shows how this very helpful feature looked in V9.5.1.2:
Figure 1: Hover text prior to V9.6.
In V9.6, when you hover over a variable name, it not only shows the definition, but also the context of that definition. If it’s a subfield in a data structure, the data structure name appears, and if it’s a nested data structure, you see all the levels of nesting in the hover text. If it’s defined in an externally described file, the file and record name appear in the hover text, and if it is defined in multiple files, you’ll see them all. If the variable was passed in as a parameter, it shows that context as well. The comment about F2 at the bottom of the hover box means that you can use F2 to “freeze” the hover box in place even after you move the mouse away from the item. This makes it easier to take advantage of the hyperlinks inside the box to navigate to the place where those items are defined. Some examples are shown in Figures 2 through 4.
Figure 2: V9.6 Hover text for a data structure subfield.
Figure 3: V9.6 Hover text for an externally described field.
Figure 4: V9.6 Hover text for a parameter.
At the risk of sounding like a late-night commercial . . . but wait, there’s more! Do you put comments in your code? If so, good for you! Even better if you place your comments on the line(s) immediately before a definition or at the end of the line of the definition. Why? Because comments in those positions will be included in the hover text in V9.6. This includes not only declarations of data items but also procedures.
For procedures, comments for internal procedures can be gathered from the lines just before the beginning of the procedure (i.e. before the P spec or the Dcl-Proc.) For external procedures the comments can be gathered from the comments just before the prototype definition, even if they are in a /Copy’d member.
I have included some examples in Figures 5 and 6 to help demonstrate this new hover text feature. In these examples, I’ve included the declarations close to the reference to them, which is of course not a realistic scenario. After all, if the declarations were always adjacent to the references in the logic, there would be no need for support like this. But I wanted you to see examples of comment positioning and its impact on the hover text.
Figure 5: V9.6 Hover text for a data item with associated comments.
Figure 6: V9.6 Hover text for a procedure with comments.
Of course, in doing this RDi is forced to make some bold assumptions about which comments relate to which items. The result is not perfect, by any means. For example, I often group constants or standalone fields together with an introductory comment. In that case, the comment will only show up for the first item. Worse yet, what about all those commented out lines of code you have hanging around in your source members? If any of them happen to be positioned just before a definition, they will show up in the hover text for that item.
The moral to this story is that descriptive comments in our code are good, and if they are positioned where RDi expects to find them they are now even better. I have a habit of putting comments for internal procedures immediately after the Dcl-Proc, not before. But you can bet that I’ll be changing that habit now and moving all those comments to allow RDi to help me understand my code better in the future.
By the way, I promised in the first tip to explain how to turn off or control these new features. I have not found a way to turn off this comment inclusion feature. If you have lots of commented-out lines of code or other kinds of “misplaced” comments, you will need to either move or remove the offending comments or just get used to ignoring them.
On some Windows installations there is a clicking sound effect that occurs in conjunction with this enhanced hover feature. If, like me, you find this click annoying, you may be interested to know that it can be turned off. To do so, go to Control Panel > Sound and choose the Sounds tab. In the Program events box, look for “Start Navigation” (I found it in the File Explorer section of the list in Windows 10) and choose (None) in the Sounds list. I use a Mac (and am grateful every day that I no longer need to load my Windows virtual machine to run RDi) so I don’t experience the sound effect issue in my everyday RDi environment.
Annotations
There are two new kinds of annotations in V9.6. One highlights any definitions that are not being specifically referenced in the code. While I can see occasions where this can be a useful feature, it’s something that I’ve turned off for myself. Many/most of the items that I found that it annotated as “not used” are actually used, even though they may not be referenced in the code. In my case, they were often data structures which I name to make their purpose clear but I never reference the structure itself. The annotation for this appears to the left of the sequence number as an “i” as shown in the example in Figure 7. Hovering over the annotation shows the message that the item is not used.
Figure 7: Unused definition annotation.
If you like this annotation for unused definitions, you won’t need to do anything to activate it because it is turned on by default. If you prefer to turn it off, it’s controlled by the base preference page for the ILE RPG parser (Figure 8).
Figure 8: Preference page to control annotation of unused definitions.
The second type of annotation I find far more useful. Compile errors can now be shown in the source as annotations instead of their previous form: the inserted pink messages. Prior to V9.6, after clicking on an error message from the Error List view, the editor positioned to the offending line and inserted the message(s) related to it in the source. Figure 7 shows how it looked.
Figure 9: Inserted compile error messages prior to V9.6.
While it was certainly helpful to have the messages in the source, they took up a lot of space and tended to get in the way. They could also sometimes wander away from the line they were associated with. While the Ctrl+F5 shortcut clears them out easily enough, they could still be annoying. So V9.6 brought with it the option (which is activated by default) to use annotations instead. The example in Figure 10 illustrates the use of a simple annotation in the margin next to the line where the error occurred.
Figure 10: V9.6 Compile error annotation.
Hovering over the annotation provides the error message(s) associated with it. (See Figure 11.)
Figure 11: Hover to see details of compile errors.
Just in case you long for the original style pink inserted messages, you can switch back to that method of pinpointing compile errors in your source. You won’t find it in the usual spot, i.e., preferences. Instead, this feature is controlled from the View menu in the Error List view itself. Click on the view menu icon (circled in red below) and use the Message Style option. While you’re there, you may want to check out some of the other options in the same menu, even though the other options were there prior to V9.6. My favorite thing to change here is under “Show Severity” where I always de-select the information level messages. (See Figure 12.) There are also controls here for when messages are inserted and removed from the source in case you want to modify the default behaviors.
Figure 12: How to control your compile message style.
And there’s more . . .
Surely after two tips I’ve covered all the significant V9.6 enhancements, right? Nope. Later I’ll look at even more new/enhanced features in V9.6, including the new merge capability of the source compare feature and a new way of collecting Code Coverage data.
RELATED STORIES
Guru: Ready Or Not, Big Changes in RDi V9.6! Part 1, Key Behavior
Guru: Confessions Of A Recovering RDi Outline Addict
Guru: How Do You Do That With RDi? Part 3: Complex Compiles
