Comment Documentation for Use In Eiffel Development Tools

When getting started with any language it's always good to start on the right foot and do things correctly. It just saves time and frustration later down the line when something needs to be changed. In this tutorial I'll introduce you to the Eiffel comment markup that allows tools, such as EiffelStudio, to extract meaningful segments of information and provide context about them.

Marking up comments is not only useful in EiffelStudio navigation but also in documentation. Marked up comments highlight class and feature names as though they were actually written in some uncomment class text. Initial impression may shy away from such mark up, I mean, why would you want comments to look like code? After all they are comments and should be distinguishable from your code for clarity. The fact of the matter is that marked up comments look nothing like blocks of code at all. Instead one or two words are highlighted to look like Eiffel a syntactically highlighted class name or feature.

Marking up is extremely simple to do and once you start you wont even realize that you are doing it. The value add of the practice will pay off as soon as your compile your first system.

Why Mark Up Comments?

Marking up comments is an excellent way to produce cross reference documentation. For any form of code review or research is makes the reader's research much more efficient. Instead of seeing the name of a class or feature which he/she then has to look up, direct access is provided through EiffelStudio to navigate to the entity being referenced. It literally takes one or two seconds compared to 10-20 of even the modest of keyboard junkies.

Another good reason for marking up references is code refactoring. The refactoring tools currently in EiffelStudio allows class and features to be renamed. When you rename a class you would want all references to that class to be changed also, no? If the renamed class references are not marked up then there is no way for EiffelStudio to guarantee that a class name in a comment is actually a reference to the renamed class, as a results the comments are not changed. This is not an issue in systems of a very modest size but almost all small projects grow. Even in a system of 20 classes it's hard to remember what class text references what classes and features.

Marking Up

So now you are convinced, or at least somewhat, let's get on with the mark up format. I warn you, this section is extremely short.

There are three styles of mark up; class, feature and a compound that is a class and feature name.

Class Name Mark Up

Class names can be marked up using the Eiffel "typeof" operator style format {CLASS_NAME}. See the listing below.

format (str: STRING; args: TUPLE): STRING -- Format a string using a format string and returns the result. -- For the formatting rules and special characters see {STRING_FORMATTER}. do ... end

Feature and Entity Name Mark Up

Feature names or locally scoped entities can be marked up using correct single quotation. This is in the form of `name', that is single back-quote (`) name single quote (').

format (str: STRING; args: TUPLE): STRING -- Format a string `str' using a format string and context argument `args' and returns the result. -- For the formatting rules and special characters see {STRING_FORMATTER}. -- Note: All format string are compiled using `compile_pattern'. do ... end

Class and Feature Name Mark Up

The final form of mark up is a combination of a reference class and feature name. It's possible you might was to reference a parent feature of a feature in another class. In order to do this you use the mark up used for class followed by the qualified call ignoring the mark up used for features and entities.

format (str: STRING; args: TUPLE): STRING -- Format a string `str' using a format string and context argument `args' and returns the result. -- For more information of formatting see {STRING_FORMATTER}.format do ... end

As a final note on the examples list here, the syntax highlighter used to show Eiffel examples does not examine the marked up class and feature names. As a result they are not highlighted as they would be in other EiffelSoftware tools.

Marking Up, Not Just For Comments

Marking up class and features name is not restricted to comments. You can also specify the markup in any type of Eiffel manifest or verbatim string declaration. Normally string mark up is reserved for description strings in a class' indexing clause but it doesn't have to be. Any class can use mark up for it's own purpose, execution or otherwise. Using marked up string also release you, the author, or any maintainer from adjusting string constants when a class or feature name has been renamed, using the refactoring tools.

An example of using the class name mark up in a verbatim string: indexing description: "[ Description for class {CLASS_NAME}. ]" release: "1.0" class CLASS_NAME end