Skip to content

docs: api: review/update docstrings #36

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.

Sign up for GitHub

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

Jump to bottom
Closed
lread opened this issue Aug 16, 2022 · 0 comments · Fixed by #41
Closed

docs: api: review/update docstrings #36

lread opened this issue Aug 16, 2022 · 0 comments · Fixed by #41

Comments

@lread
Copy link
Collaborator

lread commented Aug 16, 2022

I'll take a pass at the docstrings.

  • focus on return value and markdown args
  • more fully describe options for client/request
  • cljdocify any [[var-references]]

I'm not going to concern myself with what is/is-not part of the public API.
lread added a commit to lread/clj-http-lite that referenced this issue Aug 16, 2022
@lread
docs: review and update docstrings
f6b6681 
This exercise helped me to understand the API more deeply, hopefully it
will help our users too.

The biggest challenge was documenting `clj-http.lite.client/request`.
Its previous docstring was way too vague for me to understand, as a
user, what is available.

Also challenging is the lack of definition of the supported API.
I'm guessing our documented API is currently including lots of
unnecessary internals.

I reviewed all existing docstrings and updated where I thought I could
be clearer and/or more consistent. I added no new docstrings.

Also: added cljdoc.edn to explicitly list our docs.

Closes clj-commons#36
@lread lread mentioned this issue Aug 16, 2022
Merged
@lread lread closed this as completed in #41 Aug 16, 2022
lread added a commit that referenced this issue Aug 16, 2022
@lread
docs: review and update docstrings (#41)
9d73e5d 
This exercise helped me to understand the API more deeply, hopefully it
will help our users too.

The biggest challenge was documenting `clj-http.lite.client/request`.
Its previous docstring was way too vague for me to understand, as a
user, what is available.

Also challenging is the lack of definition of the supported API.
I'm guessing our documented API is currently including lots of
unnecessary internals.

I reviewed all existing docstrings and updated where I thought I could
be clearer and/or more consistent. I added no new docstrings.

Also: added cljdoc.edn to explicitly list our docs.

Closes #36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

docs: review and update docstrings lread/clj-http-lite
1 participant
@lread