eiffelroom - Inheriting comments - Comments

The contract viewer's right-click issue

peter_gummer — Thu, 28 Feb 2008 04:12:39 -0800

Paul, you mention three possible fixes for the right-click issue seen in the sneak preview of the contract viewer.

The last would be sad, so let's not think about that.
The second would be disappointing: it's so neat that it pops up simply by hovering the mouse there.
The first is intriguing. You say that hovering the mouse over a feature would display a small beam. What would the user have to do, then, to open the contract viewer? Click on the beam? Move the mouse down a bit to hover over the beam? This sounds a bit disappointing too.

A fourth option would be to leave it as it is, but make sure that right-clicking works. Isn't this possible? If I try to right-click on a feature but the contract viewer has popped up unexpectedly, is there any reason why the right-click can't be forwarded to the feature stone underneath? (Not sure if I've got my pebble-drop metaphors mixed up there, but you know what I mean.)

Me, I'd want to activate it via a keyboard shortcut rather than a mouse-hover, of course ;-)

A few Notes

paulbates — Wed, 27 Feb 2008 16:47:14 -0800

We are aware of the right click issue and it will be addressed.

I put a preview of the contract viewer in the editor to ensure any annoyances are worked out before the release. I mentioned this in one of the 6.2 release notes, release 6.2.7.2075.

There are a few things that might happen with this:

The drop down is shrunk to a small beam under the feature name text, so it does not pop up accidentally or get in the way.
The pop up time out will be longer so it does not pop up too soon, with a key modifier to show it immediately.
It will be removed.

We need to get this right because in the future the mechanism will be used in various forms throughout EiffelStudio. As it stands, what you see probably wont be what is released. There is quite a bit of logic already there to determine when to show the token options. Any feedback is welcome, we want to get this right without being annoying.

In reference to Greg's remarks, it's not a tool tip. In the future you'll be editing contracts directly on the "assistance window". As I've said these types of windows will be placed through EiffelStudio in future releases, not just in the editor.

I like it if it works

peter_gummer — Wed, 27 Feb 2008 14:30:57 -0800

I have no problem with this innovation. Where I get annoyed as a user is when an innovation gets in the way of standard user interface conventions. (Pick and drop is the classic example of that. Until recently, it impeded the use of context menus, and even today there is no drag and drop.) In 6.2.7.2437, we have this nice preview of the contracts tooltip, and I like it, but a couple of times already it has popped up when I was attempting to right-click a feature.

The trouble with this sort of thing is that it's easy to prototype and get people saying "Wow!", but it's very difficult to get it right. So I'd be glad to see this in 6.2, as long as it's very thoroughly tested! I would expect to see an option in Preferences for turning it off.

I'm not sure if there is any

manus_eiffel — Mon, 25 Feb 2008 20:59:45 -0800

I'm not sure if there is any standard for tooltips, but if you look at Visual Studio they have something very similar. They do not have a button, but they have expandable tree views in the tool tip. Not exactly the same, but it looks like tooltips are not just messages anymore, you can interact with them.

Nice, but..

gcompestine — Mon, 25 Feb 2008 12:40:53 -0800

Shouldn't the "Edit Contracts..." button be in a popup menu instead of a tooltip?

This seems like a very non-standard add-on to tooltip functionality. I do think the tooltip is a good idea, and I also believe strongly that Eiffel Vision should be migrating closer to supporting standard behavior rather than adding more departures from it.

If it is documented as a standard for Windows or some other common user interface, could you please refer me to the document?

Thanks,

Greg

It definitely makes sense to

manus_eiffel — Tue, 19 Feb 2008 10:22:43 -0800

It definitely makes sense to use Precursor and we will go with it for now since it seems that people prefer it even though it is not used for implementation but for specification.

Precursor vs. Original

ericb — Tue, 19 Feb 2008 01:20:25 -0800

The keyword Precursor refers to the implementation, but the notion of precursor feature is implementation free, as defined in ECMA 367-2, section 8.10.27: "A precursor of an inherited feature is a version of the feature in the parent from which it is inherited." On the other hand, Original may be confused with the definition of Origin of a feature, section 8.5.1, which is the class where the feature was first introduced. Considering these two definitions, I clearly prefer Precursor because what we mean is the comment in the precursor feature (i.e. the version of the feature in the parent), not the comment that appeared when the feature was first introduced. In the example below:

class A

feature

   f

         -- Comment 1

     do

         ...

     end

end

class B

inherit

   A

      redefine

          f

      end

feature

   f

         -- Comment 2

     do

         ...

     end

end

class C

inherit

   B

      redefine

          f

      end

feature

   f

         -- <Precursor>

     do

         ...

     end

end

what we mean is -- Comment 2 and not -- Comment 1.

Comments are clearly not implementations

peter_gummer — Mon, 18 Feb 2008 15:21:49 -0800

If it appears in a comment, it's clearly not referring to an implementation, so I can't see any opportunity for confusion if you use -- <Precursor>.

But if you really don't want to do that, then how about:

-- <ditto>

Which people might abbreviate to:

-- <">

;-)

We thought about Precursor,

manus_eiffel — Mon, 18 Feb 2008 14:40:00 -0800

We thought about Precursor, but because it refers to an implementation rather than to a specification we thought something else would be better. This is why we have settled for -- <Original>; this is definitely not a firm decision yet as we are waiting for more feedback.

Precursor

peter_gummer — Mon, 18 Feb 2008 14:28:37 -0800

But seriously, why not use the same keyword that Eiffel code uses to denote the inherited routine:

-- <Precursor {MANU}>

Then people only have to remember one word. You'll have newcomers confused trying to remember which word they have to use in which context.

(Not that I'm particularly fond of the keyword Precursor -- I would have found inherited more intuitive -- but Precursor it is, so let's use it!)

I have a comment

peter_gummer — Mon, 18 Feb 2008 14:20:48 -0800

-- <Original {MANU}>

Original comments, everywhere

paulbates — Mon, 18 Feb 2008 12:26:03 -0800

For those that have read your blog, as of rev#72341 the inherited/original comments can also be seen in the code browsing tools such as the Features and Class Tools.

Also, it's worth mentioning that the <Original> comment can be injected anywhere in a redefined feature's comments, it's not an exclusive system. It is entirely possible to author new comments for a new feature and implant <Original> on one of the new lines. The end results merging the written comment with the inherited comment of a redefined feature.

Inheriting comments

manus_eiffel — Mon, 18 Feb 2008 10:32:48 -0800

I don't know if you are like me but often when you redefine a feature, I used to copy/paste the comments so that I still know what the feature is supposed to do in english terms (in addition to the contracts of course). In 6.2, we are introducing a new facility so that in the editor and in the flat-view of the feature you do not have to do the copy/paste.

I'm going to use classes from the compiler to show the new feature. The definition of {TYPE_A}.good_generics states:

good_generics: BOOLEAN is

            -- Has the base class exactly the same number of generic

            -- parameters in its formal generic declarations?

        require

            is_class_valid: is_class_valid

        do

            Result := True

        end

and now in my descendant LIKE_TYPE_A, I just do the following:

good_generics: BOOLEAN is

            -- <Original>

        do

            Result := actual_type.good_generics

        end

Basically, what we are doing is that the comment -- <Original> is a placeholder to get the inherited comment. In the EiffelStudio editor, it is shown by the following tooltip when you leave your mouse pointer over the feature name for a few seconds:

Note that if you do put no header comment in the redefined routine, we will still show the inherited comment. However it was felt that having -- <Original> was a clear indication for the reader of the class that the header comment was not forgotten.

And if you inherit the routine from various ancestors, you can choose which ancestor's comment to take by using the following syntax -- <Original {MY_ANCESTOR}>.

If you have any feedback on this new feature, please let us know by dropping a comment.