[erlang-questions] Spec is diabolical IMHO

Richard O'Keefe ok@REDACTED
Fri Sep 28 01:03:22 CEST 2012

On 28/09/2012, at 7:20 AM, Mike Oxford wrote:

> I'm in the "I like C/C++ .h files," just like I like the concept of IDL files.
> I can very quickly scan through the file (just like Erlang -export areas) and see what's available and the parameters.
> Otherwise you're either bogged down going through the code or relying on a secondary toolpass to generate documentation which then has to be hosted somewhere.
> "What was the exact parameter list?"
> "Hold on, let me fire up a browser to get to the file/site."
> "Nevermind, I just opened up the header and I got it."
> Headers have downsides, to be sure, but they have a very nice usage pattern for figuring out WTF this object is, what it appears to do and maybe how it plays into the overall architecture of the system.
> Also, I can grep a header dir and not get slammed with a wall of implementation crap.

Let me commend WYSINEYH.

What You See is Not Everything You Have.

I don't agree with Bertrand Meyer about everything, but there are a
lot of really good ideas behind Eiffel.  One of them is the tools
that come with it.  Recall that Eiffel has multiple inheritance and
_lightweight_ embedded documentation.

Eiffel comes with two helper programs:

	Takes an Eiffel class and gives you a listing with all
	the inheritance folded out, so you see *every* method
	in the class, not just the added ones.

	Takes an Eiffel class and strips out the method bodies;
	it gives you a pretty-printed listing of the method
	interface and documentation.

The combination

   short flat
	Gives you the interfaces and documentation for everything
	exported from a class.

Come to think of it, JavaDoc, pldoc, Haddock, and erldoc try to
do something a bit similar, but heavier weight.

What I'm thinking of is an editor mode that (possibly temporarily)
hides everything but the -specs and selected comments.

That way you get the benefit of HAVING everything in the one file
but not the cost of having to READ everything.

More information about the erlang-questions mailing list