Использование строки документации __doc__

Здесь нет ни преимуществ, ни недостатков. Это встроенный функционал. Выбирать использовать или нет предстоит вам или вашему руководителю. По факту у каждого объекта существует атрибут __doc__. Она может быть либо None, либо строковым литералом.

>>> a = 5
>>> a.__doc__
"int([x]) -> integer\nint(x, base=10) -> integer\n\nConvert a number or string to an integer, or return 0 if no arguments\nare given.  If x is a number, return x.__int__().  For floating point\nnumbers, this truncates towards zero.\n\nIf x is not a number or if base is given, then x must be a string,\nbytes, or bytearray instance representing an integer literal in the\ngiven base.  The literal can be preceded by '+' or '-' and be surrounded\nby whitespace.  The base defaults to 10.  Valid bases are 0 and 
2-36.\nBase 0 means to interpret the base from the string as an integer literal.\n>>> int('0b100', base=0)\n4"
>>> type.__doc__   
"type(object_or_name, bases, dict)\ntype(object) -> the object's type\ntype(name, bases, dict) -> a new type"
# а вот тип данных None, парадоксально, но docstring не имеет, то есть имеет значение None
>>> None.__doc__
>>> 

Строковой литерал применяется в функциях, классах и модулях. При исполнении данная строка игнорируется, но распознается компилятором и помещается в атрибут __doc__ классов, функции и модулей. Первая строка после объявления класса, функции или модуля является каноническим. Только так docstring распознается.

Пример с директивой help, которая умеет их распозновать

>>> def func(t):
...   """Test docstring""" 
... 
>>> help(func)
Help on function func in module __main__:

func(t)
    Test docstring

И как пример, не верное использование

>>> def func(t):
...   t += 5
...   """Not canon, this is not a docstring"""     
... 
>>> help(func)
Help on function func in module __main__:

func(t)