r/emacs•
TLATER

Are there any good packages for doc comments?

As an absolute addict of documentation-driven design, the one thing I keep finding myself struggling with when coding in emacs is doc comments.

Especially python doc comments, when trying to follow the Google style guide, are very frustrating because it's almost impossible to indent them correctly by default.

Of course yasnippet does a good job at solving that with a little bit of setup. But it's a annoying if you switch between languages a lot - emacs' great strength is that it knows how to handle so many out of the box. I'd prefer not to spend 2-3 hours hacking a snippet before I can work.

There are a few language-specific packages, but they generally aren't very consistent and outdated or buggy.

Surely there must be a better way, considering many languages share doc comment styles anyway (javadoc seems to be particularly common, for example).

Posted Oct 24, 2016, 12:09 PM UTC

176
jbranso•

You could also try out org-babel. But I'm not aware of any major pieces of software that use literate programming...

3
TLATEROP•

I'm definitely looking for a more standard solution.

Literate programming is nice, but it's better at explaining code than at explaining interfaces, and it's not how my current projects work.

3
_compunaut_•

As soon as you have a mode which handles the indentation of one comment style you can use something like edit-indirect

1
TLATEROP•

There's also polymode and the likes, but that would still require me to write the actual modes myself. Also parsers for each language to extract arguments and return values automatically, etc.

I'm not against writing a package myself, but it would be nice to have a package that's already in use if there is one.

1
_compunaut_•

I don't know of any existing mode for that, but who knows. Many modes support eldoc so it should be possible to use that to extract the arguments.

1
triogenes•

I'll give a shout out to sphinx-doc.el since that's what I'm currently using for python.

1