Mastering PyCharm Transcripts
Chapter: The Editor
Lecture: Creating documentation
0:00 Let's return to our Wizard attack here
0:02 notice there's no real documentation
0:05 there's a few things inferred by PyCharm,
0:07 and that's pretty sweet that it does that
0:09 but what if we wanted real documentation
0:11 like what does it return the bool for
0:14 if it was successfully able to attack the Creature or if it defeated the Creature
0:18 or you know what does that even mean right,
0:21 so we would like to give it more information
0:23 of what types of Creatures can it take and so on.
0:26 So, let's go over there, CMD B or you know go to definition,
0:30 so we'll come over here and in Python
0:33 the way we create documentation for a method
0:36 is we put the doc string at the beginning
0:39 and you say triple quote " " ", type some stuff and a certain format that describes it
0:45 and then you put another triple quote " " ", and that string is what's called a doc string.
0:51 Well watch what happens if I triple type quote, one, two, three
0:56 that's cool it auto matches the closing quote;
1:00 if I hit enter— boom, look at that, it tells me here is my parameter,
1:04 here is a return value, so I'll say
1:06 the attack method will attack and potentially kill
1:13 and the return value is going to be this bool
1:21 and it's going to be true if Wizard wins, false if they are defeated.
1:31 And then this Creature, this will be a Creature object
1:38 which can fight another Creature,
1:47 Creatures can attack each other in this thing.
1:50 We could even come down here and say type Creature
1:53 and say it's a Creature one can spell, you can say it like this right
1:58 again spelling is hard.
2:00 So we'll come over here and we'll even see this type so that's pretty cool as well.
2:03 Now let's just switch back, over here
2:06 and I'll hit F1 to put my help and it says here's the documentation,
2:11 look, notice this part about well it needs to have these features, it's gone,
2:15 it's like that's a Creature, straight up,
2:17 you're a Wizard, it's a Creature, you fight and get a boolean.
2:20 And it says the attack method will attack and potentially kill the Creature
2:25 and here is the Creature, which happens to be a Creature
2:30 we could see what to do with that in a second,
2:33 creature object we can find another one
2:36 and here the return value is true if the Wizard wins false if it's defeated
2:39 so that little bit of help, remember what did I type,
2:42 I basically came over here and typed triple quote enter,
2:47 boom, and then just filled out the details, like so.
2:50 And we get this nice Python style documentation
2:55 and then we can view it over here and you can even navigate
2:58 so like if the creature had a documentation, well it doesn't
3:01 but you know, let's go and give the creature documentation.
3:04 We'll say same thing triple quote, the base type for all combative Creatures
3:12 something like that, now let's try this trick, one more time.
3:16 Okay, here's our Creature, we click on this,
3:19 boom, the base type for all combative Creatures.
3:21 That's super nice, right, so you'll see
3:23 both quickly we can discover the documentation for built-in standard library things
3:28 like random.choice or string.format
3:32 for external packages that have this defined or even within our own type
3:36 and when we are doing with our own types
3:39 PyCharm gives us tons of support
3:41 on creating the right syntax for generating that documentation.