Some docstring cleanup

[danielfromearth]

A couple of additional docstring suggestions pulled from this comment in PR #580:

• I think this comment for rebuild_auth() can be put into the method docstring instead
• there's an out-dated and unnecessary type annotation here that can be removed
• I think Google docstring style prefers a spacing between summary line and expanded description (see examples here). Here are the places I found that look like a line spacing could be added:
  • in refresh_tokens()
  • in get_s3_credentials()
  • in the two hits methods: hits() and hits()
  • in provider()
  • in set_requests_session()
  • in get_fsspec_session()
  • in get_requests_session()

[mfisher87]

Thanks @danielfromearth !

[Sherwin-14]

@danielfromearth Hey Daniel, I had some doubts regarding this issue. First of all, on removing the type annotations means we'll have to remove all the instances in the code related to isn't that the case? I just wanted some clarity over this. Also the kerchunk.py has two public functions and in the issue description you had suggested that we'll need to add the "Placeholder" to only one public function in there. So which one is it? It will help a lot if you chime in.

[mfisher87]

I think what we're looking for is on this line:

https://github.com/Sherwin-14/earthaccess/blob/f8901ade489c8c211658ec13a5757ce1b6259ff9/earthaccess/auth.py#L96

there's a docstring "type annotation" indicating the type of system is Env. In Python code without real type annotations, this can be useful, but since we have real type annotations, it's redundant. It's also incorrect, the real type of system is Optional[System]. So we're just looking to remove the docstring type annotation.

Personally, I think we should not add Placeholder anywhere else. We used that solely to enable docstrings with metadata (Parameters or Returns) but without a subject line to not be borked by the code formatter. We considered adding a subject line out of scope for that PR.