How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on.

I have always wonder why comments like this can be so ordinary in documents of libraries in dynamic languages:

/**
 * cb: callback    // where's the arguments & effects?
 */
 func foo( cb )

Maybe the common attitude is "you can look into source code on your own after all" which pushes people into leaving minimalist comments like this.

But it seems like there should be a better way to comment callback functions.

I've tried to comment callbacks in Haskell way:

/**
 * cb: Int -> Char
 */
func foo(cb)

And to be fair, it's usually neat enough.

But it gets into trouble when I need to pass some complex structure. The problem being partly due to the lack of type system:

/**
 * cb: Int -> { err: String -> (), success: () -> Char }  // too long...
 */
func foo(cb)

Or I have tried this too:

/**
 * cb: Int -> { err: String -> (),
 *              success: () -> Char }  // better ?
 */
func bar(cb)

The problem is that you may put the structure in somewhere else, but you must give it a name to reference it. But then when you name a structure you're about to use immediately looks so redundant:

// Somewhere else...
// ResultCallback: { err: String -> (), success: () -> Char }

/**
 * cb: Int -> ResultCallback    // better ??
 */
func foo(cb)

And it bothers me if I follow the Java-doc like commenting style since it still seems incomplete. The comments don't tell you anything that you couldn't immediately see from looking at the function.

/**
 * @param cb {Function}  yeah, it's a function, but you told me nothing about it...
 * @param err {Function} where should I put this callback's argument ??
 *                       Not to mention the err's own arguments...
 */
func foo(cb)

These examples are JavaScript like with generic functions and parameter names, but I've encountered similar problems in other dynamic languages which allow complex callbacks.