search

pegasystems / pega-datascientist-tools

Pega Data Scientist Tools
https://github.com/pegasystems/pega-datascientist-tools/wiki
Apache License 2.0
33 stars 27 forks source link

Missing docstrings in V4 #280

Open StijnKas opened 1 week ago

StijnKas commented 1 week ago

pdstools version checks

Issue description

Creating issue for tracking purposes. While refactoring for the V4 version of pdstools, not every class/module/method/function was given docstrings. Now that I've included numpydoc as a pre-commit hook, this becomes an issue. I'd like to use numpydoc to validate new incoming docstrings automatically, but we can't do that today as it's complaining about many missing docstrings instead. This'll be quite some work, but obviously it's necessary to get the API docs up to speed as well.

Reproducible example

-

Expected behavior

Unfortunately (for us), every class, method, function should have a docstring, conforming exactly to the numpy docstring standard. I say unfortunately, because this is a lot of work.

Installed versions

``` V4 ```
operdeck commented 1 week ago

Should we really? It’s an internal tool with not that many users. I rather spend time to broaden the scope of the analyses and make them better - eg AGB or IH coverage or the ADM Healthcheck now that is going to be served via DJS.

Op vr 8 nov 2024 om 10:40 schreef Stijn Kas @.***>

pdstools version checks

-

I have checked that this issue has not already been reported.

I have confirmed this bug exists on the latest version https://pypi.org/project/pdstools/ of pdstools.

Issue description

Creating issue for tracking purposes. While refactoring for the V4 version of pdstools, not every class/module/method/function was given docstrings. Now that I've included numpydoc as a pre-commit hook, this becomes an issue. I'd like to use numpydoc to validate new incoming docstrings automatically, but we can't do that today as it's complaining about many missing docstrings instead. This'll be quite some work, but obviously it's necessary to get the API docs up to speed as well. Reproducible example

-

Expected behavior

Unfortunately (for us), every class, method, function should have a docstring, conforming exactly to the numpy docstring standard. I say unfortunately, because this is a lot of work. Installed versions

V4

— Reply to this email directly, view it on GitHub https://github.com/pegasystems/pega-datascientist-tools/issues/280, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABEVTKF4V43AIAFHC6GIMM3Z7SBHDAVCNFSM6AAAAABRNC3OXCVHI2DSMVQWIX3LMV43ASLTON2WKOZSGY2DGNBXGY2DCNY . You are receiving this because you are subscribed to this thread.Message ID: @.***>

StijnKas commented 1 week ago

@operdeck I don't believe they are exclusive and I think there may be some middle-ground (only requiring valid docstrings for new code), but I do think there's quite some benefits to having proper docstrings so that it's more self-documented. But definitely good to not do docstrings for the sake of docstrings, so maybe this issue is worded a bit strongly.