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