Unusual docstring format

[gdude2002]

While this isn't really a huge problem, you may wish to reformat your docstrings according to the established formats.

PEP 287 recommends that reST (reStructuredText) format be used, but Epytext is popular as well - They're used because Python IDEs are often able to parse them to get more information about the things they document, for example, for auto-completion.

[tasdikrahman]

Didn't know about this. Will be refactoring the docstrings to conform with PEP 287. reST seems like an obvious choice here.

Thanks for pointing out 😄

[gdude2002]

👍 - it's not a big deal, but it's one of those useful little things that gets overlooked a lot.

[tasdikrahman]

Fixed in 295ee0b.

Closing issue.

[balta2ar]

:param and :returns are great but I also suggest adding :type and :rtype fields. That helps A LOT in the long run.

[tasdikrahman]

An example if you don't mind @balta2ar ? Would surely add it up

[balta2ar]

Something like this:

    @defer.inlineCallbacks
    def _update_models(self, cur_time,
                       new_server_stats, max_time_server):
        """
        Updates global models and models of budget objects.

        @param cur_time: Current time
        @type cur_time: datetime.datetime

        @param new_server_stats: New server stats
                (received since last update).
        @type new_server_stats: ProcessedServerStats

        @param max_time_server: Timestamp (unix timestamp) of latest
                update got from server[s].
        @type max_time_server: float

        @return: Update models running deferred.
        @rtype: defer.Deferred(dict[str, ComputationResult])
        """

[gdude2002]

Yuri, that isn't rst. It would be more like this:

• :type param: str - Expected type of a parameter
• :rtype: bool - Type/s of object/s returned by the function
  On 4 Dec 2015 15:49, "Tasdik Rahman" [email protected] wrote:

Reopened #6 #6.

—
Reply to this email directly or view it on GitHub
#6 (comment).

[balta2ar]

@gdude2002 Absolutely, that was just an example of type/rtype that I've grabbed from some project.