docstrings for all functions/methods

[dkriegner]

We should have some brief documentation on what the various parameters of functions are (including a note on the datatype they should have). I propose to use a common docstring format : see here: https://realpython.com/documenting-python-code/ I suggest to use reStructuredText or the numpy/scipy convention.

You might also want to look into type hints: https://docs.python.org/3/library/typing.html

originally raised in a code comment https://github.com/dkriegner/micro-flakes/commit/096b627f65e62e67a3fee786b33e3a1f5c79fcdd#r130727919

[ji-ze]

If I use

def function(a: int)
    ...

and I write a string, the script falls out. My solution chacks if it is an integer. If it isn't, the script asks me again.

[dkriegner]

your comment has nothing to do with docstrings. I'll answer in a separate issue.

[ji-ze]

Is the following example OK?

def take_webcam_image(path, filename):
    '''This function takes a photo with a webcam. The first parameter is the path of a new photo. The second parameter is the name of a new photo.'''
    cap = cv2.VideoCapture(0, cv2.CAP_MSMF)
    # cap.set(14, 500) # gain
    # Turn off auto exposure
    cap.set(cv2.CAP_PROP_AUTO_EXPOSURE, 0)
    # set exposure time
    cap.set(cv2.CAP_PROP_EXPOSURE, 0)
    # set resolution
    cap.set(cv2.CAP_PROP_FRAME_WIDTH, 5472)
    cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 3648)
    # Check if the webcam is opened correctly
    if not cap.isOpened():
        raise IOError("Cannot open webcam")
    while True:
        ret, frame = cap.read()
        # cv2.normalize(frame, frame, 100, 255, cv2.NORM_MINMAX)
        # frame = cv2.resize(frame, None, fx=1, fy=1, interpolation=cv2.INTER_AREA)
        cv2.imshow('Input', frame)
        cv2.imwrite(filename=f'{path}/{filename}.jpg', img=frame)
        # print(frame)
        c = cv2.waitKey(1)
        if c == 27:
            break
    cap.release()
    cv2.destroyAllWindows()
    return 0

[dkriegner]

For this one I would suggest

def take_webcam_image(path: str, filename: str):
    """Takes a photo with a webcam and stores it in path/filename."""

Since the variables have a speaking names I believe no extra description is needed. I would add type hints which tell the user it will be strings.

One other comment: Why does take_webcam_image has return 0 on the end? I do not see you using the return value in your code.

For a function like this one:

def gamma_correct(image, gamma):
    """Here one needs more details about the processing of image.

    gamma is the value ...
    """

I believe you need more explanation because gamma needs some more definition.

[ji-ze]

I've comment the majority of comments. I've thought I should write return 0 if I don't have an output. It means the function ends without an error.

[dkriegner]

I think return 0 is a C-language standard, but in Python its not needed. If there is no return it will effectively be return None. But if your code does not need a return value then I would leave this statement out

[ji-ze]

OK, I've made it