search

Cloud-CV / evalai-cli

:cloud: :rocket: Official EvalAI Command Line Tool
https://cli.eval.ai
BSD 3-Clause "New" or "Revised" License
55 stars 63 forks source link

Update docstrings #87

Open guyandtheworld opened 6 years ago

RishabhJain2018 commented 6 years ago

@isht3 Please resolve the conflicts here!

guyandtheworld commented 6 years ago

@RishabhJain2018 Done!

RishabhJain2018 commented 6 years ago

@isht3 Can you please confirm that you have added the changes suggested by @varunagrawal?

guyandtheworld commented 6 years ago

@RishabhJain2018 @varunagrawal Isn't this a bit overkill? Like most of the functions are very similar to each other. So aren't the sections notes, warns and references of very little use and very redundant?

RishabhJain2018 commented 6 years ago

@isht3 Let me take a look again! Till then please complete the other pending PR. I'll update you on this.

varunagrawal commented 6 years ago

@isht3 you're correct. You need to have the minimum args and return value descriptions as that is common to all functions and methods. Exceptions/warnings should be added as needed.

In the case of references and section notes, if you are doing something in a non-standard way, you should make a note of that in the references, explaining your decisions so that the next person to look at your code nods in agreement. A good example is anything that caused significant debate in the PR on what is the right way to do that, and depending on various constraints, what was the reasoning. Another reason for section notes is type of data expected in case that is not vehemently clear, or what does the method do if it performs some crazy state change (which this code does not).

Remember, we want to generate docs from these, so anyone reading the docs should get a good impression of what to expect just from these docstrings.