Added docstring for the endpoints scripts #287
Conversation
|
Good job, however I'd not include parameters in the docstrings. Type hints render those useless. You already see what are the parameters and their type from the signature of the class/method. So it doesn't really bring any value, but on the other hand you will see yourself catching up with docstrings whenever you change the signature. |
|
Thank you, actually it's for generating a document in pydoc format, and that way it kinda explains what each parameter stands for, that's why i did it like that, i thought it'd be helpful. |
|
Not sure if API docs still a thing these days. I think proper usage examples serve much better as documentation.On 19 Jun 2023 09:43, Black-Pearl25 ***@***.***> wrote:
Thank you, actually it's for generating a document in pydoc format, and that way it kinda explains what each parameter stands for, that's why i did it like that, i thought it'd be helpful.
—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>
|
|
Actually, I have submitted another pull request for an updated version of the documentation of thehive4py, based on the current one. The updated documentation includes proper usage examples of the API. Initially, I felt the need for a docstring, which is why I wrote it and thought it would be beneficial for clarity. Hence, I submitted the pull request. However, if you believe it is unnecessary, I can always close this pull request. |
|
Don't get me wrong.Docstrings are good. Relisting parameters are not. If we really want to generate API docs using some tool, I'd expect the tool to work out signature definitions using the type hint annotations, as those are the source of truth nowadays, not some free text description.So to clarify, I think it makes sense to describe what a method does, also please consult PEP257 to create standard docstrings.Then good to go.On 19 Jun 2023 12:08, Black-Pearl25 ***@***.***> wrote:
Actually, I have submitted another pull request for an updated version of the documentation of thehive4py, based on the current one. The updated documentation includes proper usage examples of the API. Initially, I felt the need for a docstring, which is why I wrote it and thought it would be beneficial for clarity. Hence, I submitted the pull request. However, if you believe it is unnecessary, I can always close this pull request.
—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>
|
|
Alright thank you, i appreciate you clarifying things, i'll do that. |
|
@Kamforka is this going to be considered or should be closed as |
|
We could do this as part of #301 |
|
Will be done in #301 |
No description provided.