python學習筆記-爲自定義類或者函數編寫help文檔，以及進行文檔測試

在python中咱們能夠利用help("模塊名")或者help(類名)的方式來查看類或者函數的文檔。可是它們是如何編寫的呢？
其實它們在類最前面或者方法的最前面用"""三個雙引號包裹了多行註釋。這些內容就會被Python當成幫助文檔。

那幫助文檔通常會寫什麼內容呢？主要包括如下內容：

• 該類或者函數的主要做用

• 傳入的值和輸出的值

• 一些特殊狀況的說明

• 文檔測試內容

以上內容是我的的總結，可是並無看到相關的資料。

咱們來舉一個例子：

class Apple(object):
    """ This is an Apple Class"""

    def get_color(self):
        """
        Get the Color of Apple.
        get_color(self) -> str
        """
        return "red"

在python terminal輸入

>>> from CallDemo import Apple
>>> help(Apple)

Help on class Apple in module CallDemo:

class Apple(__builtin__.object)
 |  This is an Apple Class
 |  
 |  Methods defined here:
 |  
 |  get_color(self)
 |      Get the Color of Apple.
 |      get_color(self) -> str
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

利用doctest進行文檔測試

咱們在註釋中咱們也能夠doctest模塊進行文檔測試。

例如，咱們添加了文檔測試內容後以下所示：

class Apple(object):
    """
    This is an Apple Class

    Example:
        >>> apple = Apple()
        >>> apple.get_color()
        'red'
        >>> apple.set_count(20)
        >>> apple.get_count()
        400

    """

    def get_color(self):
        """
        Get the Color of Apple.
        get_color(self) -> str
        """
        return "red"

    def set_count(self, count):
        self._count = count

    def get_count(self):
        return self._count * self._count


if __name__ == '__main__':
    import doctest

    doctest.testmod()

因爲咱們寫了

if __name__ == '__main__':
    import doctest

    doctest.testmod()

因此以上文檔測試只有在以入口文件執行的時候纔會進行文檔測試。所以並不會在實際應用在執行文檔測試。