Improve docstring of clojure.java.io/delete-file to be clearer about intent of silently arg

Description

clojure.java.io/delete-file docstring takes an optional second arg `silently` and says:

This is confusing. The intent is that in the case of a failure, it will by default throw an exception. Or if the optional second arg is supplied and truthy, it will be returned instead.

Initially reported: https://groups.google.com/d/msg/clojure/T9Kvr0IL0kg/wcKBfR9w_1sJ

Approach: Make docstring sentence clearer per Stu's suggestion in comments:

Patch: clj-1159.patch

Environment

any

Activity

Show:
import
February 10, 2013, 8:01 PM

Comment made by: atkaaz

I kinda just realized it affects all versions since and including 1.2, because it appears that its implementation was the same since then.

If it's not meant to return the result of the delete, maybe it should specifically return nil and/or the doc say something?

Sean Corfield
February 10, 2013, 8:21 PM

As noted in a thread on the Clojure ML, you can pass a known value in the second argument position to detect a delete that failed:

(clojure.java.io/delete-file some-file :not-deleted)

This returns true on success and :not-deleted on failure.

However the docstring could be better worded to make that intention clear. Perhaps:

Delete file f. Return true if it succeeds. If silently is nil or false, raise an exception if it fails, else return the value of silently.
This allows you to detect whether the delete succeeded without catching an exception by passing a non-true truthy value as the second argument.

Stuart Halloway
July 21, 2015, 2:20 PM

I think 'If silently is nil or false, raise an exception if it fails, else return the value of silently.' is sufficient

Completed

Assignee

Unassigned

Reporter

import

Labels

Approval

Ok

Patch

Code

Fix versions

Affects versions

Priority

Minor
Configure