Тъй като вече знаем как да пишем многоредовите коментари, можем да използваме тройни единични кавички или тройни двойни кавички. Ние използваме низ от документация, когато искаме да опишем нашите функции, така че да можем да получим документацията, когато имаме нужда от нея. Някои IDE ви предоставят документация, като просто задържите курсора на мишката над името, а някои подчертават определени ключови думи. Но факт е, че документните низове в NumPy са много по-гъвкави, отколкото в други езици. Docstring е низов литерал, който се появява в началото на дефиницията на функцията. Трябва да предоставим конкретни стойности, докато използваме документационните низове в случаи на функции, класове и т.н.
Когато използваме документни низове с функции, трябва да предадем аргументите. Когато ги използваме с класове, предаваме атрибутите и методите. В случай на модули, трябва да предоставим списък с класове и функции. В случая на пакета предаваме списъка с модули с функционалност. Така че основно целта на документационния низ е, както обяснява името, че помага с документирането на нашия код. Ние правим документация, така че ако някой използва нашия код в бъдеще, той ще може да разбере нашия код и логиката зад нашия код с помощта на docstring. Вградените функции също имат документни низове в тях; можем да използваме функцията на help(), за да разгледаме документационния низ от вградени функции.
Има няколко разлики между коментари и документни низове. Коментарите се игнорират от интерпретаторите, но документните низове не се игнорират от интерпретаторите. Паметта се разпределя за документни низове. Коментарът е описание на кода, но от друга страна, документните низове ни казват целта на кода.
Синтаксис:
Синтаксисът за запис на документните низове в NumPy е:
'''Docstring съобщение'''
Или
'''Документен низ съобщение'''
Моля, обърнете внимание, че docstring не е функция или метод, така че няма правилен синтаксис. Единственото нещо, което трябва да се отбележи тук е, че започваме документалния низ с три единични кавички или три двойни кавички. Пишем нашето описание на кода и го завършваме отново с три единични кавички или три двойни кавички в края. Няма нещо задължително за писане на документни низове. Просто трябва да поставите три единични или двойни кавички преди и след описанието на вашия низ.
Пример 1:
За да разберем документационните низове по по-добър начин, нека изпълним пример. В този пример, след като включим библиотеката NumPy, ние просто декларираме променливата „a“ и друга променлива „b“. След това създаваме нашия docstring, който казва „Нека добавим променливи „a“ и „b“. В нашия случай това е лесен пример, но ако нашият код е сложен, това помага много на програмиста да разбере кода. След това сумираме променливите „a“ и „b“ и съхраняваме техния резултат в друга променлива, която е „c“. Накрая отпечатваме стойността на променливата “c”. Сега изпълняваме нашия код.
импортиране numpy като напр.а = 1
b = две
'''Да добавим променливи a и b'''
° С = a+b
печат ( ° С )
Това е нашият изход от дадената част от кода. Можем да видим, че системата не е дала никаква грешка относно неправилен синтаксис или нещо друго за ред7 от нашия код. Освен това системата не е отпечатала нашия документационен низ. Вместо това, той отпечата само изхода на нашата променлива „c“, в която казахме на нашата система да отпечата. Това показва как работят документните низове. Следващият път, когато нов програмист се опита да работи върху нашия код, той ще разбере какво правим с помощта на нашия docstring. Но той няма да бъде отпечатан като изход, така че потребителят на кода няма да бъде обезпокоен от него.
Пример 2:
Сега изпълняваме сложен пример, за да разберем работата на документния низ. Първо включваме библиотеката NumPy и след това пишем низ от документи, в който обясняваме следващия ред код, където обясняваме инициализацията на масива. Добавяме и документните низове в другата част на кода. Сега, ако споделим този код с всеки нов разработчик на Python, без да добавим документационните низове, някак си ще му бъде трудно да знае работата и целта на този код. Той първо трябва да потърси функциите, които сме използвали. Но ако добавим документен низ към нашия код, ще бъде лесно за другите разработчици да разберат кода, без да изучават повече за функциите. Не сме ограничени да добавяме коментари към някои ограничения; коментарите могат да бъдат от един или повече от един ред. Може също да се добави повече от веднъж в код. След това импортирайте NumPy като np.
'''Създаване на променлива, към която ще предадем масив с размер 1x6'''масив = напр. масив ( [ единадесет , 22 , 33 , 44 , 55 , 66 ] )
'''присвояване на масива на функцията tofile(), за да бъде записан във файла с име arr'''
масив . tofile ( 'arr.bin' )
'''показване на файла чрез функцията fromfile'''
печат ( напр. от файл ( 'arr.bin' , dtype = вътр ) )
Както е показано в следния фрагмент, документните низове не се показват в изхода, което означава, че не засяга изхода или компилацията на кода. Документните низове се игнорират по време на процеса на компилиране.
Заключение
В това ръководство научихме за docstrings в NumPy. Сравнихме документационните низове с коментари и обяснихме разликата между тях. Научихме синтаксиса на документните низове и как да пишем документните низове в нашия код. Освен това се опитахме да обясним какво представляват документните низове в NumPy и как работят с помощта на примери. Накрая отбелязахме, че те са от съществено значение за програмистите. Няма да повтаряме важността на документните низове в NumPy. Просто ще кажем, че трябва да използвате документационните низове във вашия код. В NumPy стилът на писане на docstrings е най-популярният. Той се използва широко в програмистката общност, за да се информират взаимно за работата и функционалността на своите кодове. Това ръководство ще ви помогне да започнете с NumPy docstrings. Опитахме се да покрием повечето от това, от което ще се нуждаете, като използвахме документационните низове в NumPy.