Conversation
Step 1 for #197: Initial docstring & arg names review. Args lists naming review, now using: - `path` (or `-path` suffix) for a file or dir (which might be a string, Path, or File) - `dir` or `-dir` suffix means always directory - `file` or `-file` suffix means always a file (not to be confused with File) - `target` (was using `dest` sometimes) - `source` (was using `src` sometimes) Note: I added private `babashka.fs/path*` to be used when there would otherwise be a collision between `path` arg and `path` fn. Consistent language for docstrings. I.e., now consistently "Returns ... " Consistently describe `opts` under Options:, and as keywords. Get much less wordy for xdg-* and reworded some other fns. As requested, now vague on return values. We now only explicitly state `Path` for fs/path, and `File` for fs/file. Vaguely documented return types of fns that are simple pass-thrus to JDK. Tests mostly already covered these, but filled missing gaps. Added "Coercions and Returns" and "Argument Naming Conventions" sections to README.
|
damn, this is stellar work, lee! |
Contributor
|
I took a brief look but I found this more confusing than it was before:
I think this sentence gives the initial impression that multiple paths are returned. Therefore I think starting with |
Contributor
|
Sorry for my brief response, in a hurry today. Will reply more carefully later. |
Contributor
Author
|
Thanks @NoahTheDuke! @borkdude, thanks for initial peek. One example: before: After: Is it the "path for |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Step 1 for #197: Initial docstring & arg names review.
Args lists naming review, now using:
path(or-pathsuffix) for a file or dir (which might be a string, Path, or File)diror-dirsuffix means always directoryfileor-filesuffix means always a file (not to be confused with File)target(was usingdestsometimes)source(was usingsrcsometimes)Note: I added private
babashka.fs/path*to be used when there would otherwise be a collision betweenpatharg andpathfn.Consistent language for docstrings.
I.e., now consistently "Returns ... "
Consistently describe
optsunder Options:, and as keywords.Get much less wordy for xdg-* and reworded some other fns.
As requested, now vague on return values.
We now only explicitly state
Pathfor fs/path, andFilefor fs/file.Vaguely documented return types of fns that are simple pass-thrus to JDK. Tests mostly already covered these, but filled missing gaps.
Added "Coercions and Returns" and "Argument Naming Conventions" sections to README.
Please answer the following questions and leave the below in as part of your PR.
This PR corresponds to an issue with a clear problem statement.
This PR contains a test to prevent against future regressions
I have updated the CHANGELOG.md file with a description of the addressed issue.