self-documenting-code

I am wondering what the commenting format is in order to have self-documenting code using Sphinx's sphinx-apidoc utility. I am able to get this utility to generate a set of reStructuredText files for each python file, but these files still need to be filled in. I am looking for a way to get this utility, or some other Sphinx utility to generate documentation from the python codes docstrings. I understand this would require becoming familiar with a conventional commenting format, and I am hoping to be pointed to this reference material. Thanks! mzjn, thanks for the comment. your second link

Is it worth learning the convention or is it a bane to readability and maintainability? Considering that most people that use Hungarian Notation is following the misunderstood version of it, I'd say it's pretty pointless. If you want to use the original definition of it, it might make more sense, but other than that it is mostly syntactic sugar. If you read the Wikipedia article on the subject, you'll find two conflicting notations, Systems Hungarian Notation and Apps Hungarian Notation . The original, good, definition is the Apps Hungarian Notation , but most people use the Systems Hungarian

In Java, for example, the @Override annotation not only provides compile-time checking of an override but makes for excellent self-documenting code. I'm just looking for documentation (although if it's an indicator to some checker like pylint, that's a bonus). I can add a comment or docstring somewhere, but what is the idiomatic way to indicate an override in Python? UPDATE (23.05.2015): Based on this and fwc:s answer I created a pip installable package https://github.com/mkorpela/overrides From time to time I end up here looking at this question. Mainly this happens after (again) seeing the