Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!ncar!boulder!ccncsu!olender
From: olender@cs.colostate.edu (Kurt Olender)
Newsgroups: comp.lang.eiffel
Subject: Re: class environment, suffix .env
Message-ID: <OLENDER.90Mar9151751@sor.cs.colostate.edu>
Date: 9 Mar 90 22:17:51 GMT
References: <5193@ccncsu.ColoState.EDU> <263@eiffel.UUCP>
Sender: news@ccncsu.ColoState.EDU
Organization: Colorado State University, Fort Collins, CO 80525
Lines: 32
In-reply-to: bertrand@eiffel.UUCP's message of 8 Mar 90 22:16:30 GMT


The case of the undocumented ".env" file extension reveals a more
general point.

When a "require" clause of an exported routine contains a non-exported feature
(say a boolean function that computes a rather complex condition on the input
to the routine), "short" does not print that require clause.  That is how
short is documented to work, and it indeed does.

Thus, the automatic documentation mechanism will not record in it's public
interface what may be a rather important restriction on the form or
values of some input data.  Certainly, if a call violates this restriction
the client will fail, but the client programmer will have no idea why
without looking at the original source.  He or she may see a message generated
from a require clause label, but that label does not appear in the short
output either.

On the other hand, the client programmer doesn't need to know the names
of features that aren't public, and can't use.

perhaps short should print the label of any require clause containing
a private feature.  The output of short environment.e might then look
something like:

	  require
	  	once_set;
                file_created: not f.Void;
		good_suffix
          do

presumably, then, the programmer must use some descriptive name for
the preconditions.