Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docstrings to functions #20

Closed
lwgray opened this issue Oct 2, 2017 · 7 comments
Closed

Add docstrings to functions #20

lwgray opened this issue Oct 2, 2017 · 7 comments

Comments

@lwgray
Copy link
Contributor

lwgray commented Oct 2, 2017

Overall:
A docstring should be included at the top of code to summarize project @AdiChat This might be good for you to do

Specifically (see example below): This could be done by other contributers

  1. Docstrings should be added to each function.
  2. The docstrings in each function must include argument type with short description
  3. The docstrings in each function must include a return type
    def is_cow(sound):
        ''' Checks if cow makes inputted sound 
        Args:
            sound(str): sound the animal makes
        Returns:
            bool: True for success, False otherwise.
        '''
        if sound == 'moo':
            return True
        else:
            return False
@yashasingh
Copy link
Member

yashasingh commented Oct 2, 2017

@AdiChat I would like to work on this issue.

@AdiChat
Copy link
Member

AdiChat commented Oct 2, 2017

@yashasingh Go for it. 👍

@luisdcb97
Copy link

If the function does not explicitly return do we still need to provide a description beyond returns None?

@lwgray
Copy link
Contributor Author

lwgray commented Oct 2, 2017

I think that for the functions that don't return anything, just include a general description of the function and it's inputs. I would exclude the Returns portion of the docstring in these functions. @AdiChat what do you think? Also, don't use Returns None. None is an object in python.

Please chime in if you think it should be handled differently

@AdiChat
Copy link
Member

AdiChat commented Oct 2, 2017

I agree 👍

@lwgray
Copy link
Contributor Author

lwgray commented Oct 6, 2017

Need to reopen issue... I found several minor issues with the docstrings and will submit a PR

@AdiChat
Copy link
Member

AdiChat commented Oct 6, 2017

Sure 👍

@AdiChat AdiChat reopened this Oct 6, 2017
lwgray added a commit to lwgray/vidsum that referenced this issue Oct 6, 2017
@bhaveshAn has done a wonderful job but the docstrings have minor flaws and were changed.
1. Some of the parameter types were missing thus added
2. Unncessary notes about obvious aspects of function were include thus deleted
3. Non-consistent styling of docstrings, thus thry were reformatted for style and consistency
4. Docstring text exceeded PEP8 line length of 79 characters thus reformatted to abide by std

Issue OpenGenus#20 and PR OpenGenus#30
@lwgray lwgray closed this as completed Oct 6, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants