1
00:00:05,480 --> 00:00:10,350
so getting back to doc strings again now for
simple functions and classes you

2
00:00:10,350 --> 00:00:14,480
doc string can really just be a single
line summary in which case just included

3
00:00:14,480 --> 00:00:18,260
all on one line with the quotes on the
same line you can see here obviously with my

4
00:00:18,260 --> 00:00:22,150
doc string here I've got the quotes in different
lines because we got multiple lines of

5
00:00:22,150 --> 00:00:27,230
text their but often you want to provide more
information then there for multi line

6
00:00:27,230 --> 00:00:30,440
doc string may be more appropriate
will be more appropriate in the

7
00:00:30,440 --> 00:00:35,650
circumstances so the first line of a
multi line doc string should be a

8
00:00:35,650 --> 00:00:40,420
brief summary with further details
included after a blank line so can see

9
00:00:40,420 --> 00:00:43,770
here we've got the brief overview of
what this class is about a blank line

10
00:00:43,770 --> 00:00:45,620
and then we got more information

11
00:00:45,620 --> 00:00:49,560
after that blank line now it can
be difficult to strike a balance between

12
00:00:49,560 --> 00:00:56,340
being to brief and to verbose and the
doc strings for this song class are a little

13
00:00:56,340 --> 00:00:59,730
bit too verbose at the moment by
themselves they are ok but the doc

14
00:00:59,730 --> 00:01:03,260
string for the init method doesn't
really add anything that isn't already

15
00:01:03,260 --> 00:01:07,060
included in the doc string for the class in
other words this doc string down here

16
00:01:07,060 --> 00:01:10,860
doesn't really give us much more
information other than introducing a typo their

17
00:01:10,860 --> 00:01:18,220
which I'll fix then it has already been specified in this class doc string and just to see in this action we

18
00:01:18,220 --> 00:01:22,360
can see this a bit better by looking at one of the uses for
doc string which is providing help

19
00:01:22,360 --> 00:01:27,220
now strangely IntelliJ gives a warning
about an unexpected argument to the help

20
00:01:27,220 --> 00:01:32,230
function this actually cause is caused
by the doc string for help itself now I'm

21
00:01:32,230 --> 00:01:36,550
gonna come back to that but for now when we
run the program after this line

22
00:01:36,550 --> 00:01:39,300
24

23
00:01:39,300 --> 00:01:42,410
type help.....

24
00:01:42,410 --> 00:01:50,410
and you can see we've got this warning here unexpected argument so that
actually caused by the doc string for help

25
00:01:50,410 --> 00:01:51,360
itself

26
00:01:51,360 --> 00:01:55,440
now I'm gonna come back to that but for now if
you run the program just right click and

27
00:01:55,440 --> 00:02:00,000
run song to make sure I'm running the right Python file and scroll up a

28
00:02:00,000 --> 00:02:02,870
little bit

29
00:02:02,870 --> 00:02:08,479
you can see the documentation that is for this particular class so you could see here

30
00:02:08,479 --> 00:02:11,800
the doc string is used by the help function to
provide information on the song class so

31
00:02:11,800 --> 00:02:16,930
by calling the help function which is part of
Python its automatically added this and

32
00:02:16,930 --> 00:02:20,200
put this information in the form of
documentation which we can read

33
00:02:20,200 --> 00:02:24,940
because they added this bit here data inscriptions define here but also this bit here grabbing

34
00:02:24,940 --> 00:02:30,750
the information from our doc strings so close that down and the other thing we can do we can

35
00:02:30,750 --> 00:02:36,140
request help on a particular method so if we go and
change line 24 here so instead of just

36
00:02:36,140 --> 00:02:42,690
doing generic help for the song class so gonna
change to do just add so I'm going to get

37
00:02:42,690 --> 00:02:52,310
some help for the init method so.....

38
00:02:52,310 --> 00:02:56,790
what we want to do is we don't want to call the init method we want to just get

39
00:02:56,790 --> 00:03:00,060
some information get some help on it so
make sure I've remove those parenthesis

40
00:03:00,060 --> 00:03:05,990
as you saw me doing and if I run it again we can see now helps gonna come back and show

41
00:03:05,990 --> 00:03:10,660
us the information just for the init method
itself and not for the entire class that was

42
00:03:10,660 --> 00:03:16,360
their last time and the other thing you can do is you can
just print this out so I can comment out line 24

43
00:03:16,360 --> 00:03:24,900
.....

44
00:03:24,900 --> 00:03:32,540
so via the doc attribute if you run
that we've got to class doc string

45
00:03:32,540 --> 00:03:36,210
there that is another way of accessing
information instead of using the help

46
00:03:36,210 --> 00:03:40,350
function but the big difference their is
where as help will display the doc string

47
00:03:40,350 --> 00:03:42,050
for all the methods as well

48
00:03:42,050 --> 00:03:46,730
printing it out in this way as we just did their with the
print only gives the doc string for the object

49
00:03:46,730 --> 00:03:51,010
specified which in this case is the
class so to display the doc string for the

50
00:03:51,010 --> 00:03:56,200
init method then we have to specified
explicitly so if I show you what I mean

51
00:03:56,200 --> 00:04:05,390
so it won't be just init method we'll have to do something like.....

52
00:04:05,390 --> 00:04:15,510
....and if we run that we've got the song
init method showing their underneath the

53
00:04:15,510 --> 00:04:20,890
output which was from the class so really
at this point in the courses shouldn't

54
00:04:20,890 --> 00:04:25,240
be anything really surprising about the
output and if you believed on what I have

55
00:04:25,240 --> 00:04:29,630
said that everything in Python is an
object then this should really be

56
00:04:29,630 --> 00:04:33,780
anything surprising about the way we just access it
just in case though what I've done there is

57
00:04:33,780 --> 00:04:39,250
print the doc attribute of the init method
now functions and methods in Python are

58
00:04:39,250 --> 00:04:44,590
also objects so they have attributes just like
any other object so the doc string as

59
00:04:44,590 --> 00:04:50,410
we have defined it for the init method here the code on line 11 through 18 the

60
00:04:50,410 --> 00:04:55,030
doc string for the init method is really
too much and adds nothing as I mention to

61
00:04:55,030 --> 00:05:00,140
the class doc string so I'm gonna remove it
and but I will also add it back temporarily by

62
00:05:00,140 --> 00:05:03,890
assigning the string to the methods doc
attribute so I'm gonna do that I'm going

63
00:05:03,890 --> 00:05:06,220
to just copy this and I'm just going to

64
00:05:06,220 --> 00:05:14,050
and get rid of that for now and what I'm going to do is show you another way that we can add the documentation if

65
00:05:14,050 --> 00:05:25,950
we wanted to and we can do is this way under the print I can put...

66
00:05:25,950 --> 00:05:35,990
....

67
00:05:37,240 --> 00:05:46,910
....

68
00:05:46,910 --> 00:05:54,300
....so lets run that and you can see we got the class

69
00:05:54,300 --> 00:05:59,370
doc string there and also the
init doc string showing so that's just an

70
00:05:59,370 --> 00:06:04,610
alternate way that you can add a doc string if you
want to create it in code that way now note

71
00:06:04,610 --> 00:06:10,970
that this code won't work in Python 2 in
Python 2 the doc attribute which we've

72
00:06:10,970 --> 00:06:12,190
written to on line 19

73
00:06:12,190 --> 00:06:16,940
its not writable on the Python 2 but that's not really a problem

74
00:06:16,940 --> 00:06:20,510
because obviously you wouldn't really do
that in a real application if you gonna

75
00:06:20,510 --> 00:06:24,140
provide a doc string and probably should be
included with the object as I

76
00:06:24,140 --> 00:06:31,260
did originally if the code that I cut out that was originally
lines 11 from 11 onwards but this does

77
00:06:31,260 --> 00:06:36,920
demonstrate that methods can have a attributes and gives you a taste of the power in Python so

78
00:06:36,920 --> 00:06:43,940
in Python if you want to do it thhen you probably can that is the general philosophy even if it's not a good idea

79
00:06:43,940 --> 00:06:48,370
to actually do that so lets move on now
and continue with our record collection

80
00:06:48,370 --> 00:06:53,240
so the next step is to create an album
class its going to store the songs that will

81
00:06:53,240 --> 00:06:57,710
make up an album so what I'm going to do is
delete the doc string code that I used to demonstrate

82
00:06:57,710 --> 00:07:05,090
the doc string attribute and add a new class so basically
delete all this code from line 16 onwards which we

83
00:07:05,090 --> 00:07:10,350
don't need anymore let's go ahead and
create this class album

84
00:07:11,080 --> 00:07:16,520
.....

85
00:07:18,010 --> 00:07:29,260
...again the convention is that extra blank line

86
00:07:29,260 --> 00:07:44,030
their and....

87
00:07:44,030 --> 00:07:47,030
....

88
00:07:49,120 --> 00:08:02,350
....

89
00:08:03,650 --> 00:08:06,650
....

90
00:08:07,720 --> 00:08:28,550
....

91
00:08:28,550 --> 00:08:30,790
...

92
00:08:30,790 --> 00:08:34,929
....

93
00:08:41,809 --> 00:09:35,110
....so that is our class album doc string so lets start writing a bit of code so we define our init method....

94
00:09:35,110 --> 00:09:48,720
....

95
00:09:50,960 --> 00:10:06,120
....

96
00:10:06,120 --> 00:10:17,070
....next we want to create

97
00:10:17,070 --> 00:10:21,570
this add song method but before we do that
we need to then save the track

98
00:10:21,570 --> 00:10:23,270
so....

99
00:10:23,270 --> 00:10:26,330
.....

100
00:10:27,680 --> 00:11:05,350
....

101
00:11:06,130 --> 00:11:13,740
....

102
00:11:15,400 --> 00:12:07,930
....

103
00:12:07,930 --> 00:12:19,230
.....

104
00:12:19,230 --> 00:12:31,280
....

105
00:12:31,280 --> 00:12:36,460
.....so once again there's really
nothing that can be said in the doc string

106
00:12:36,460 --> 00:12:43,260
for the init method that isn't covered in
the class doc string so its worth adding a note

107
00:12:43,260 --> 00:12:48,050
about the add song method though so following the guidelines of pep 257 which I hope

108
00:12:48,050 --> 00:12:52,280
you've read it by now the first line is a brief
summary of what the method does then the

109
00:12:52,280 --> 00:12:55,770
individual arguments are documented and
you can see that's the case there that

110
00:12:55,770 --> 00:13:03,980
I've done that in the add song doc string on line 41 now if an argument is optional then its a good idea to describe

111
00:13:03,980 --> 00:13:07,490
what will happen if the arguments not
provided in this case the song is gonna

112
00:13:07,490 --> 00:13:09,690
be added to the end of the list

113
00:13:09,690 --> 00:13:14,110
the album class also uses a list to
store the songs and provides a method this

114
00:13:14,110 --> 00:13:18,750
add song method add_song for
adding songs to a list and in addition

115
00:13:18,750 --> 00:13:22,360
its got a filed for the artists which is a next
class and I'm gonna be adding to this

116
00:13:22,360 --> 00:13:26,650
program in the next video so having this
artist object stored in the album

117
00:13:26,650 --> 00:13:31,440
objects can cause problems I because the
artist class itself will also hold a list of

118
00:13:31,440 --> 00:13:33,820
the artist published albums

119
00:13:33,820 --> 00:13:38,520
but I'm gonna talk more about that when was seen the
artist class so lets end this video here now then

120
00:13:38,520 --> 00:13:40,890
will continue on with this project in the
next video