Eiffel Code Comments

Minimum EiffelStudio Version: 6.2

Precursor Comments

Precursor comments are a new mechanism added to EiffelStudio 6.2 to replicate a parent feature declaration's comments in the redefined/effective feature. The purpose of the mechanism is to reduce comment duplication, ease comment mainteance and facilitate augmentation. The precursor comment declaration supports

deferred class BASE
 
feature -- Access
 
    f (a_arg: BOOLEAN): INTEGER
            -- The comments for the feature.
            --
            -- `a_arg': Comments for the argument.
            -- `Result': Comments for Result.
        deferred
        end
 
end

class EFFECTIVE
 
inherit BASE
 
feature -- Access
 
    f (a_arg: BOOLEAN): INTEGER
            -- <Precursor>
        do
        end
 
end

The use if -- <Precursor> is optional but is supported for existing code out there that do not have comments due to lax implementation. It is strongly recommended that you use -- <Precursor> comment mark up to indicate to any reader the feature is a redefinition or effective implementation of a parent feature declaration.

Comment Augmentation The precursor comments declaration also supports augmentation. All a comment author has to do is to write additional comments before and/or after the precursor comment declaration. As a requirement, the precursor comment declaration must appear on a separate line for no other purpose except for clarity. Failure to do so will results in the rendering of the comments as they are declared in the feature, i.e. with -- <Precursor> as is.

   f (a_arg: BOOLEAN): INTEGER
           -- Below are the original comments from {BASE}.f
           -- <Precursor>
           --
           -- Some additional  comments about `f'.
       do
       end

Use the code browsing facilities of EiffelStudio the reader will be presented with the full expanded comment, for the effective version of feature f:

Below are the original comments from {BASE}.f
 
The comments for the feature.
 
`a_arg': Comments for the argument.
`Result': Comments for Result.
 
Some additional  comments about `f'.

Multiple Redefinitions and Selection With Eiffel supporting multiple inheritance a scenario will arise where two inherited features redefine are joined in a descendant. By default the precursor comment declaration is replaced by the first located inherited feature comment, which may cause documentation irregularities. Because precursor comments are not signification to compilation they are not checked during compilation, such as is the way with the use of Precursor, resulting a compile time error when not selecting the parent class to call into. This can cause documentation irregualrities because there is no guarentee that they feature comments viewed one project will be the same in another. To facilitate correct documentation the precursor comment declaration can use an optional select clause, just like using Precursor in the Eiffel code.

f (a_arg: INTEGER): BOOLEAN
        -- <Precursor {BASE}>
     do
     end

This will have exactly the same effect as using -- <Precursor> when f is made effective/redefined from a single parent. However, when making effective/redefining from multiple parents then comments will come from the parent class declaration in BASE.

Again, because precursor comments do not affect compilation they are not checked at compile time. Specifying an incorrect class will yeild a warning message in EiffelStudio's code browsing tools, to the effect:

-- Unable to retrieve the comments from redefinition of {CLASS_NAME}.

Library Documentation Generation Precursor comments are supported in all code browsing/documentation facilities, whether is be the integerated Contract Viewer, the Feature Relation Tool or the Eiffel documentation generation facilities. Using --Precursor will ensure the comments are replicated in the