[erlang-questions] Spec is diabolical IMHO

[Richard O'Keefe]

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:

   flat
	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.

   short
	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.