Have ideas to improve npm?Join in the discussion! »

    selfexplanatory

    0.0.1 • Public • Published

    selfexplanatory.js

    Make your functions and methods self-explanatory with this simple wrapper.

    Bring documentation right where it's needed

    Whatever you're creating, a library or an API or a widget - if you want someone to use it, let them do so without even looking for the documentation. You know they prefer it that way.

    Works in the browser and in nodejs. (npm install selfexplanatory)

    What it does

    Whenever someone sees the explained function in developer tools, on an object listing etc. it will show the instructions instead of bits of its definition.

    If the function gets called incorrectly, It will throw an error containing complete usage information. No need to browse documentation anymore!

    Let's explain how it works

    explain( <object:explanation>, <function: yourmethod> )
        // returns: function with some special behaviour
    

    A more complete example maybe:

    myMethod : explain({
        args: "<string: url>,<function: success callback>",
        description: "does stuff",
        returns: "string: result",
        validator: function (url) {
            return (typeof url === "string");
        }
    }, function (url, callback) { ... });
    

    The explanation object consists of the following:

    • args required a single line describing arguments of the function
    • description required any description of the function you want to give
    • returns optional just say what gets returned
    • validator optional a function that will get called before the actual explained method with the same arguments. If the function returns something falsy, an error is thrown with the whole explanation in it. If validator returns truthy, your method gets called.

    explained method will correctly resolve this reference.

    When an invalid call is made, this is thrown:

    Usage: function( <string: url>,<function: success callback> )
    does stuff 
    returns: string: result
    

    I don't recommend explaining constructor functions and prototypes, because you loose the instanceof feature.

    Install

    npm i selfexplanatory

    DownloadsWeekly Downloads

    1

    Version

    0.0.1

    License

    Apache v2

    Last publish

    Collaborators

    • avatar