How to write pydoc and multi-line comments

20161209

Using Perl for a net 3 days since I started writing Python

Conclusion about usual comments

Except for the here-document alternative, ''' exists only for pydoc, and all other comments should be written in # [^ 1].

[^ 1]: The source of pydoc itself is written that way ... At the very least, I wish I could specify = begin, = end, = cut of perl ...

code

--Confirmed in 2.6, 2.7, 3.4 ――In a tactical sense, we do not consider whether function nesting or class in if block is possible.

foo.py


#!/usr/bin/env python
# -*- encoding: utf-8 -*-
'''
about NAME

DESCRIPTION
'''

__author__  = 'bunzaemon'
__version__ = '1.0'
__date__    = '2016/12/09'

x = 42
print (x)
'IGNORED comment'

def foo ():
    # of course ignored
    'DEF: foo'
    'IGNORED comment'
    def bar ():
        'DEF: bar <= IGNORED'

class Clas:
    'CLASS: Clas'
    def __init__ (self):
        'CLASS DEF: __init__'

if 1:
    'IGNORED comment'
    y = 42
    print (y)
    def buz ():
        'DEF: buz'
        def bux ():
            'IGNORED comment'
    class Clas2:
        'CLASS: Clas2'

if 0:
    z = 42
    print (z)
    class Clas3:
        'IGNORED comment'

Execution result

--ʻU'...'` is useless => 2.6 series is moss. [^ 2] --It seems confusing to write a comment by relying on the IGNORED comment. [^ 3]

[^ 2]: 2.6 series If you don't have to think about it, you should add it. [^ 3]: My future self

$ python --version
Python 2.6.6
$ python ./foo.py
42
42
$ pydoc ./foo.py
Help on module foo:

NAME
    foo - about NAME

FILE
    /PATH/TO/foo.py

DESCRIPTION
    DESCRIPTION

CLASSES
    Clas
    Clas2

    class Clas
     |  CLASS: Clas
     |
     |  Methods defined here:
     |
     |  __init__(self)
     |      CLASS DEF: __init__

    class Clas2
     |  CLASS: Clas2

FUNCTIONS
    buz()
        DEF: buz

    foo()
        DEF: foo

DATA
    __author__ = 'bunzaemon'
    __date__ = '2016/12/09'
    __version__ = '1.0'
    x = 42
    y = 42

VERSION
    1.0

DATE
    2016/12/09

AUTHOR
    bunzaemon

Recommended Posts

How to write pydoc and multi-line comments
How to write Python document comments (Docstrings)
How to write async and await in Vue.js
XPath Basics (2) -How to write XPath
How to write a metaclass that supports both python2 and python3
[ROS] How to write Publisher and Subscriber on one node
How to write a Python class
How to write soberly in pandas
Flask reuse How to write html
How to install and configure blackbird
How to use .bash_profile and .bashrc
How to install and use Graphviz
How to write Docker base image
How to write Django1.9 environment-independent wsgi.py
Notes on how to write requirements.txt
How to solve slide puzzles and 15 puzzles
Offline real-time how to write E11 ruby and python implementation example
Repeated @ app.callback in Dash How to write Input and State neatly
[Linux] How to subdivide files and folders
How to split and save a DataFrame
Qiita (1) How to write a code name
How to read pydoc on python interpreter
How to set optuna (how to write search space)
How to install and use pandas_datareader [Python]
Bind to class to read and write YAML
python: How to use locals () and globals ()
Various comments to write in the program
[Python] How to calculate MAE and RMSE
How to use Python zip and enumerate
Compress python data and write to sqlite
How to write this process in Perl?
How to use is and == in Python
How to write Ruby to_s in Python
Summary of how to write AWS Lambda
How to use pandas Timestamp and date_range
How to install fabric and basic usage
How to write the correct shebang in Perl, Python and Ruby scripts
How to write urlfetch unittest on GAE / P
How to use lists, tuples, dictionaries, and sets
Introducing Sinatra-style frameworks and how to use them
How to generate permutations in Python and C ++
How to create explanatory variables and objective functions
Answer to "Offline real-time how to write F02 problem"
[Python] How to read data from CIFAR-10 and CIFAR-100
How to write regular expression patterns in Linux
Data retrieval from MacNote3 and migration to Write
How to convert SVG to PDF and PNG [Python]
How to write a ShellScript Bash for statement
Answer to "Offline Real-time How to Write F01 Problem"
How to switch between Linux and Mac shells
[Python] How to use hash function and tuple.
Answer to "Offline Real-time How to Write E13 Problem"
How to write a named tuple document in 2020
[Go] How to write or call a function
How to install Cascade detector and how to use it
How to write a ShellScript bash case statement
How to plot autocorrelation and partial autocorrelation in python
[Python] How to write type annotations for Callable objects treated as variables and arguments
[Note] How to write QR code and description in the same image with python
[Python] [Django] How to use ChoiceField and how to add options
How to write a GUI using the maya command