[erlang-questions] Request feedback on example project

[Richard A. O'Keefe]

I've now written an AWK script to insert the extra blank lines
I wanted, and I found it helped me a *lot*.

On 5/02/16 1:52 am, zxq9 wrote:
> On second thought, I think the extra newlines actually improve *reading*
> but may somewhat impare *scanning*.
s/impare/impair/

Fair comment.  Thing is, I was trying to *read* the code.

For scanning the code, a scheme that begins every blob with
%%@doc
or
%%@private
&c is unhelpful, because all I ever see as I skip forward is those
uninformative lines.  When my eye (or the text editor's cursor)
comes to rest, I want it to be resting on the function name.

This means that to skip through the code in vi I need to do
/^[a-z']/ .

Let's take a look at the first thing in zuuid.erl.

%% @doc
%% Starts the zuuid application, spawning a supervisor and a worker to 
manage
%% state generation details for version 1 and 2 UUIDs and ensure duplicates
%% will not occur even at high call frequencies (as suggested in
%% <a href="http://tools.ietf.org/html/rfc4122#section-4.2.1">RFC 4122, 
4.2.1</a>).
%%

WHAT starts the application?

The problem here is that I'm not so much reading internal documentation
as I am some sort of assembly code for internal documentation.  The
information I *need* before I read these words, the information that *will*
be displayed in formatted documentation before these words, is in *this*
representation of the documentation many lines later.

Since the -spec line has the function name and may well list the
argument names and give a helpful name for the result (hint: Result is
not a particularly helpful name), I personally would find it more
readable if the order were

-spec <name>(<arguments>) -> <result>
  ...
%%@doc
....
%%

name(...) -> ...

because in this order I would at least know what the @doc was *about*.

In this order it might make sense *not* to have a blank
line between the -spec and @doc because the @doc would
be a grammatical continuation of the -spec.

Maybe everybody else just runs files through edoc and puts
that in one window while they edit code in another.