Add mechanism to include variable/function documentation?

[NateEag]

Hey, I just re-discovered this project while working on a small Emacs library.

While writing my elisp documentation, I realized I wanted to call out particular variables and functions as things a user might want to customize.

It seemed like a good place to use the docstrings I've written for those functions and variables, rather than having to maintain a list of interesting vars and functions by hand in the commentary section.

Would you accept a PR to add a mechanism for embedding variable and function names/docstrings in the generated readme?

I was thinking of using comments starting with ;;% to mean 'evaluate this block as elisp and embed the result in the generated doc', but that might be overkill.

Any thoughts?

[thomas11]

Hi NateEag,

I'm not so fond of the idea of evaluating elisp and embedding the results, simply because I'd like to keep md-readme more simple than that. Also, I like that the generated README has the same contents than the file header.

The first part of your message, embedding docstrings of interesting variables and functions, sounds more interesting. How would the tool know which ones to embed?

[NateEag]

I'm not sure how we'd want to do it - I just figured it was a suggestion worth making.

My comment prefix idea is just a thought about how you could do it - with that syntax, you could do something like

;;% (mdr-format-variables '(var-name other-var-name another-variable))

and get the Markdown-formatted "Variables" section.

I can see why you don't like the idea - it's definitely complex, and may be more powerful than we really need.

I'll see if I can come up with any other ideas. Fundamentally, it has to involve a list of interesting vars/functions, so that's a place to start.

[NateEag]

I had long forgotten that I filed this issue.

I have learned more elisp since I filed it, and have a few more thoughts on how this could be handled:

• Call out a defcustom :group somehow in the comments, then render each custom variable in that group into a "Customization" or similar section in the Markdown document.
• Another option could be rendering a similar section based on what `quoted-vars' are mentioned in the file's comments.

I'm not sure either is a perfect solution, but they seemed interesting enough to be worth mentioning. I lean towards the defcustom group.