Choosing the Appropriate Docstring Structure

00:00 How should you tailor your docstrings for different Python use cases? For modules, docstrings should give a high-level summary of what the program does while referencing key components, related modules, or usage examples. In functions, a docstring will summarize what the function does in a single imperative sentence, and describe parameters, return values, and raised exceptions.

00:22 While in classes, they describe the class’s purpose and overall responsibility, and document important attributes and public methods.

00:32 And if you’d like a little more background on modules and the general structure of Python packages, I recommend “Python Modules and Packages: An Introduction”.

00:41 Now let’s start with examining a docstring for a module.

00:45 With modules, you’re introducing the reader to the code at a high level. It starts at the first line of the file and should explain the module’s general purpose and usage.

00:54 Here’s a module docstring for the alchemy module. It contains functions like brew_potion(). This docstring even includes example usage.

01:03 This module provides tools for crafting and managing magical potions. Example: from alchemy import brew_potion(). Call brew_potion(), passing in the list ["magic phoenix feather", "tree bark"].

01:14 And the keyword argument heat_level=3. You don’t need to write a novel, but write your description and examples so that the reader can come away with a clear idea of how they would actually use the module.

01:26 Next, let’s look at another function docstring. Functions are pretty well universal. You’ll write more function docstrings than anything else, probably. You can use a single-line docstring for short, very simple functions. And for functions with more going on, multi-line docstrings are appropriate.

01:41 Check out this example: def enchant_wand(), with the parameters wand_type and level, defaulting to 1.

01:47 Enhance a wand with magical properties. Args: wand_type (str) The type of wand to enchant. level (int, optional) The enchantment level defaults to 1. Returns: str A message confirming the enchantment.

02:02 Raises ValueError if the enchantment level is invalid. If a level less than 1, raise ValueError with the message "Enchantment level must be at least 1".

02:11 Otherwise return the f-string, the result of calling wand_type.title(): "Enchanted to level {level}".

02:18 Can you remember what all three styles shown in the previous lesson have in common? Effective function docstrings should summarize the function’s behavior, as well as describe the parameters, return values, and exceptions.

02:32 And one more thing to remember: there should be a blank line separating the summary from the rest of the docstring. And feel free to add examples if needed.

02:43 Now, writing docstrings at the class level is a little more involved. Look at this example: class Potion: Represents a magical potion composed of various ingredients.

02:53 Attributes: name (str), the name of the potion. ingredients (list[str]), A list of ingredients used in the potion. potency (int), The strength level of the potion. Methods: brew(): Completes the potion and sets its potency.

03:10 describe(): Returns a human-readable summary of the potion.

03:15 The class has a dunder .__init__(), taking in self, name, and ingredients. Set self.name to name, set self.ingredients to ingredients, set self.potency to 0.

03:26 A method brew() taking in self with a docstring, """Simulate brewing the potion by calculating potency.""" Set self.potency to the length of self.ingredients times 10.

03:37 Method describe() taking in self. The docstring returns a string describing the potion and its strength. Returns the f-string: self.name, potency, self .potency. Like functions and modules, a class docstring should start with a summary describing its overall purpose.

03:56 Then it should detail the class’s attributes, including their types. In this example, name, ingredients, and potency.

04:05 It should also list any public methods for the class, which in Python means any method that you would expect users of the class to invoke. Here, that’s the brew() and describe() methods.

04:15 These don’t need detailed descriptions in the class docstring because the individual methods should have their own docstrings as well.

04:23 Alright, at this point I think you’re ready for some practice. Join me in the next lesson to try your hand at repairing some problematic docstrings.