Add comments to all py file

[JunqiZhang0]

Add more comment inside code especially init.py since this is kind of entry point of the entire LinchPin. Add comment telling developer what each file does at the beginning of each file(.py)

[14rcole]

Some of the functions already have a comment at the beginning of the function that looks like this:

    def do_action(self, provision_data, action='up', run_id=None, tx_id=None):
        """
        This function takes provision_data, and executes the given
        action for each target within the provision_data disctionary.

        :param provision_data: PinFile data as a dictionary, with
        target information

        :param action: Action taken (up, destroy, etc). (Default: up)

        :param run_id: Provided run_id to duplicate/destroy (Default: None)

        :param tx_id: Provided tx_id to duplicate/destroy (Default: None)

        .. .note:: The `run_id` value differs from the `rundb_id`, in that
                   the `run_id` is an existing value in the database.
                   The `rundb_id` value is created to store the new record.
                   If the `run_id` is passed, it is used to collect an existing
                   `uhash` value from the given `run_id`, which is in turn used
                   to perform an idempotent reprovision, or destroy provisioned
                   resources.
        """

Is that what you're looking for?

[JunqiZhang0]

I think it would be better if we add more description（comment） at the beginning of a py file to describe the function of a certain py file. Also, yes, the comment for each function needs to be added too, I found for some for functions, the comments are not updated. for some of functions they don't even have a comment @14rcole

[14rcole]

I see, I thought you meant that we needed function-level comments, I misread it. Along the same lines as the function, we should add type hinting to the functions as well

[samvarankashyap]

@14rcole What are the advantages of type hinting ? Further, Is it supported in all 3.x versions of python or are we limiting it to >=3.5 ?

[14rcole]

It helps to document the code (you know what type of data the developer of the function expects for each variable) and it can be added to linting checks (throw warnings if the data passed to a function is not of the annotated type). It was originally added in 3.0 but expanded in 3.5. That said, the current LTS version of Python is 3.6 and very few people are using anything below that. Even CentOS 7 defaulta to 3.6.8

[14rcole]

As per our discussion in the grooming session today, these comments should be function-level, not file-level