Documentation for the NSProgress indeterminate property is incorrect

Originator:matej
Number:rdar://36129961 Date Originated:19-Dec-2017 02:44 PM
Status:Open Resolved:
Product:iOS + SDK Product Version:11.2
Classification:Other Bug Reproducible:Always
 
Summary:
The documentation for the indeterminate property of NSProgress (Progress in swift) conflicts with header documentation (comments) and the actual behavior of the property.

Steps to Reproduce:
Look up the documentation for -[NSProgress indeterminate]. 

Expected Results:
It should reflect the behavior outlined in the NSProgress.h header comments.

Whether the progress being made is indeterminate. -isIndeterminate returns YES when the value of the totalUnitCount or completedUnitCount property is less than zero. Zero values for both of those properties indicates that there turned out to not be any work to do after all; -isIndeterminate returns NO and -fractionCompleted returns 1.0 in that case. NSProgress is by default KVO-compliant for these properties, with the notifications always being sent on the thread which updates the property.

Actual Results:
The documentation for  -[NSProgress indeterminate] states:

Progress is indeterminate when the value of both totalUnitCount and completedUnitCount are zero.

Version:
11.2

Notes:
The documentation also conflicts with the following statement: “Setting both totalUnitCount and completedUnitCount properties to zero indicates that there is no progress to track; in this case, *the isIndeterminate property returns false* and the fractionCompleted property returns 0.0.”.

The actual behavior of this property matches the behavior outlined in the header documentation.

Comments

Additional clarifications

To clarify the behavior at totalUnitCount = 0, completedUnitCount = 0.

Code:

let progress = Progress(totalUnitCount: 0) progress.completedUnitCount = 0 // default print("totalUnitCount: (progress.totalUnitCount)") print("completedUnitCount: (progress.completedUnitCount)") print("isIndeterminate: (progress.isIndeterminate)") print("fractionCompleted: (progress.fractionCompleted)") print("isFinished: (progress.isFinished)")

Output:

totalUnitCount: 0 completedUnitCount: 0 isIndeterminate: true fractionCompleted: 0.0 isFinished: false

So the header (NSProgress.h) documentation is correct, except for for "Setting both totalUnitCount and completedUnitCount properties to zero indicates that there is no progress to track; in this case, the isIndeterminate property returns false". This part actually matches the generated documentation.

Some other cases of indeterminate progress:

totalUnitCount: -1 completedUnitCount: -1 isIndeterminate: true fractionCompleted: 0.0 isFinished: false

totalUnitCount: -1 completedUnitCount: 0 isIndeterminate: true fractionCompleted: 0.0 isFinished: false

totalUnitCount: -1 completedUnitCount: 1 isIndeterminate: true fractionCompleted: 0.0 isFinished: false

totalUnitCount: 1 completedUnitCount: -1 isIndeterminate: true fractionCompleted: 0.0 isFinished: false

Some cases of progress that is NOT indeterminate:

totalUnitCount: 1 completedUnitCount: 0 isIndeterminate: false fractionCompleted: 0.0 isFinished: false

totalUnitCount: 1 completedUnitCount: 1 isIndeterminate: false fractionCompleted: 1.0 isFinished: true

In summary, here's the documentation that would correctly reflect the current behavior (as of iOS 13.4.1):

Whether the progress being made is indeterminate. -isIndeterminate returns YES when the value of the totalUnitCount or completedUnitCount property is less than zero, as well as if both values are zero. When progress is indeterminate -fractionCompleted returns 0.0 and isFinished returns false. NSProgress is by default KVO-compliant for these properties, with the notifications always being sent on the thread which updates the property.

By matej at May 4, 2020, 10:10 a.m. (reply...)

Please note: Reports posted here will not necessarily be seen by Apple. All problems should be submitted at bugreport.apple.com before they are posted here. Please only post information for Radars that you have filed yourself, and please do not include Apple confidential information in your posts. Thank you!