render methods should have return annotations

[wch]

The render methods in https://github.com/machow/quartodoc/blob/main/quartodoc/renderers/md_renderer.py would benefit from having return type annotations.

As things currently stand, some of them return strings and some return tuples, and there may be others as well. I've been writing some customized versions of these render methods, and I end up discovering at run time (via crashes and error messages) what type my method is supposed to return. It would be helpful to know the correct return type ahead of time.

The same probably goes for other methods besides render, but I haven't used those as much.

[machow]

Just a heads up, adding return types won't help the static type checker (which is unable to describe generic functions, and their registering / overloading behavior; see the handling of functools.singledispatch in mypy and pyright). But hopefully return types will make it easier for users reading the code

(it would be interesting to see if a mypy plugin for plum is feasible, but I suspect it's a big lift / it's behaviors might be a bit controversial, based on discussion I've seen around functools.singledispatch)

[wch]

For future reference, this is an issue in plum about making it work with pylance/pyright: beartype/plum#51

[machow]

One challenge we noticed recently is that plum will attempt to coerce return values to the annotated return type, which can produce surprising errors