[zeromq-dev] question about the documentation to provide when adding a set of functions

Pieter Hintjens ph at imatix.com
Wed Feb 5 12:05:38 CET 2014


Conventionally we have one man page per method.

We also have a standard for API construction, which you can see used
in zmq_ctx - new/destroy, etc. Please stick to this unless you have
_absolute_ reasons for doing it differently.

Before you write the man pages, can you improve the names?
"zmq_proxy_open_chain" is a long name and somewhat mysterious. You may
find a name that is more descriptive of what this object actually is
(it's not clear to me yet). Do we have closed chains? If not, why is
"open" relevant? What is the chain? A chain of proxies? I'm baffled
(and too lazy to look at the code).

The code (I finally looked at it) uses "proxy chain".

Also the code is... not nice.

    if (!hook_)
        hook_ = no_hooks;
    else
        for (size_t i = 0; i < n; i++)
            if (!hook_[i]) // Check if a hook is used
                hook_[i] = &dummy_hook;

I know we don't do code reviews but this is old-style "let's forget
about variable names and just assume we're using FORTRAN 78 registers"
stuff. It's nasty. What is 'n'?

I'd really enjoy seeing *nice* code. There's a style guide at
http://zeromq.org/docs:style.

-Pieter




On Tue, Feb 4, 2014 at 11:34 PM, Laurent Alebarde <l.alebarde at free.fr> wrote:
> Hi Devs,
>
> I have finished to develop zmq_proxy_open_chain. This one comes with a few
> functions, in particular the one to sleep/awake a socket.
>
> typedef struct zmq_proxy_open_chain_t {unsigned char _ [496];}
> zmq_proxy_open_chain_t;
> ZMQ_EXPORT int zmq_proxy_open_chain_init (zmq_proxy_open_chain_t
> **proxy_open_chain_, void **open_endpoints_,
>         void **frontends_, void **backends_, void *capture_, void **hooks_,
> void *control_, long time_out_);
> ZMQ_EXPORT int zmq_proxy_open_chain_set_socket_events_mask
> (zmq_proxy_open_chain_t *proxy_open_chain_, size_t socket_index, int state);
> ZMQ_EXPORT int zmq_proxy_open_chain (zmq_proxy_open_chain_t
> *proxy_open_chain_);
> ZMQ_EXPORT int zmq_proxy_open_chain_close (zmq_proxy_open_chain_t
> **proxy_open_chain_);
>
> I have just to update the doc before pushing and pull-request.
>
> Shall I provide one doc per function, or one only, or the same several times
> with one copy per function ?
>
> Cheers,
>
>
> Laurent
>
>
> _______________________________________________
> zeromq-dev mailing list
> zeromq-dev at lists.zeromq.org
> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
>



More information about the zeromq-dev mailing list