Add documentation for CallStack "caller" method

[pglombardo]

Per convo in gitter, it would be helpful to have this method (caller) exposed in the API documentation.

This PR adds a short method explanation and adds callstack.cr to the documentation build process.

[pglombardo]

Updated per feedback. The documentation now looks like this once generated:

I'll stick to this format/language for future PRs.

[pglombardo]

Updated per 2nd round of feedback. Keep it coming :-)

[pglombardo]

Updated screenshots:

[bew]

Those 5 lines additions will be perfect for your first contribution 😆

[pglombardo]

I should have read the doc guidelines a bit more thoroughly but I also considered that this might be a ritual hazing for first time contributor to the repo? ;-)

[RX14]

In all honestly, having this method at all is a bad idea because it encourages people to reply on stacktraces to be accurate. And in release mode, they absolutely are not. There is no way to tell which function you were called from in release mode.

[bew]

@RX14 That's right, I think it should at least be mentioned more clearly in the docs that the method is almost useless in release mode.

[pglombardo]

Ok - can someone suggest a sentence or two with a possible hint as to why this is the case?

i.e. "Note: In release mode, the usefulness of the callstack is questionable due to blah blah blah"

s/blah blah blah/<something smart>/g

Whether this method should exist at all may be true but is probably beyond the scope of this 5 line code doc PR.

[RX14]

@pglombardo it may be beyond the scope of this PR but there's little point landing this PR if we have a consensus that the method should be removed.

[straight-shoota]

That's true... what's the use case for caller? It's probably not that important to have this as a shortcut for CallStack.new (which you can always call if you need a call stack for some reason).

[pglombardo]

If we're speaking about what the best API approach would be for this functionality, I would think that a class method on CallStack would be the most logical (inspired from Ruby Kernel.caller).

Callstack.caller

The alternative is to call CallStack.new.printable_backtrace which also works but isn't as nice.

I can close this PR and make a separate one with these changes (and the method docs) if no one objects.

[ysbaddaden]

CallStack is internal implementation detail, and musn't be documented publicly.

caller is a simple method to return/printout a stack, without having to raise an exception. I use it every so often.

Release mode may inline calls, just like development inlines blocks (non captured ones). Backtrackes are never accurate, but still helpful and never wrong, whatever the optimizations.

[RX14]

As per @ysbaddaden's comment, how about we clarify that this is a human readable execution stack and add a note that it can be used while debugging. Then I think it's ready to merge.

[jhass]

I think we still want this, in case anybody wants to pick it up and finish :)

[straight-shoota]

Resolved by #9076