Mastering PyCharm Transcripts
Chapter: The Editor
Lecture: Concept: Creating documentation
0:01 In PyCharm you can pull up what they call quick documentation,
0:04 these little pop ups that document the various pieces you're working with
0:07 and this works for built-in types in the standard library
0:10 or types that we create.
0:12 So here our hero is a wizard that we created,
0:14 it derives from Creature, you can see at the top,
0:16 and it has this method attack, and PyCharm is pretty smart,
0:19 it tells you what the requirements of the creature object are and so on,
0:23 but not much more than that.
0:26 So, this could be better, right.
0:28 We should write some docs,
0:30 so if we go over here and we type " " " and then hit enter
0:34 you'll see that it's going to actually generate this skeleton piece
0:37 of the various elements we're going to enter for our documentation.
0:42 Notice, you've got to be careful
0:44 there needs to be a blank line between the param and the summary description,
0:47 that's not obvious for what you have here, but it has to do that
0:51 and then you can put things like what is the parameter,
0:53 what does it mean, what is the return value
0:55 you can also do colon type creature colon and give it a type there
0:59 and that even tells PyCharm and other things
1:01 what type that object is meant to be.
1:03 So now, we've filled it out like this,
1:07 the commands the wizard to attack a creature
1:09 and then the creatures the opponent to battle and what not, right,
1:13 so this is like a different description of the same thing
1:15 that we just did in our demo
1:18 and like I said, you can even use this type which is not proposed by PyCharm,
1:22 but this will help things understand the type hierarchies
1:25 if one is in place or like if you expect an integer
1:28 or you expect a creature, whatever.
1:30 And now if we get a quick documentation for our hero's attack
1:34 we get a much better list here,
1:37 at the bottom it commands the wizard to attack,
1:39 the creature, it's a creature from that typesetting,
1:41 the opponent in the battle and so on.
1:44 I don't document all my methods, I feel like sometimes they are so simple
1:47 that adding the documentation makes it less readable,
1:51 but certain times these sort of major functions
1:53 within your application documentations option, it's really awesome,
1:57 especially if you are writing a package for public consumption,
2:00 definitely the publicly exposed methods should be documented,
2:03 and PyCharm helps you do that.
2:05 So, now we have excellent documentation for even our own types.