fix(docs): Expand terminology and documentation guidance - #10672
Open
claucambra wants to merge 3 commits into
Open
fix(docs): Expand terminology and documentation guidance#10672claucambra wants to merge 3 commits into
claucambra wants to merge 3 commits into
Conversation
Signed-off-by: Claudio Cambra <developer@claudiocambra.com>
Signed-off-by: Claudio Cambra <developer@claudiocambra.com>
Signed-off-by: Claudio Cambra <developer@claudiocambra.com>
claucambra
requested review from
camilasan,
i2h3,
mgallien and
nilsding
as code owners
August 25, 2026 15:03
Collaborator
Author
|
/backport to stable-34.0 |
|
Contributor
|
Artifact containing the AppImage: nextcloud-appimage-pr-10672.zip Digest: To test this change/fix you can download the above artifact file, unzip it, and run it. Please make sure to quit your existing Nextcloud app and backup your data. |
i2h3
requested changes
Aug 26, 2026
| Use these terms consistently in comments and documentation. The client has two related but different engines, so vocabulary is scoped below: | ||
|
|
||
| - The **standard sync engine** is the C++ `SyncEngine`/`Folder` path, including its VFS integrations. | ||
| - The **File Provider engine** is the macOS Swift extension built on Apple's File Provider framework. |
Collaborator
There was a problem hiding this comment.
Not an extension of Swift but macOS (and a particular kind thereof) which could have also been done in Objective-C (which the file provider framework actually is written in, hence the APIs aren't that "swifty" or fit for strict concurrency).
Suggested change
| - The **File Provider engine** is the macOS Swift extension built on Apple's File Provider framework. | |
| - The **File Provider engine** is the macOS file provider extension built on Apple's File Provider framework written in Swift. |
Comment on lines
+32
to
+33
| | **state** | The current condition of an object, account, or operation. | A requested setting; use **policy** or **configuration**. | | ||
| | **status** | The result or progress of an operation, especially a transfer. | Every kind of state. Use the exact enum name when one exists. | |
Collaborator
There was a problem hiding this comment.
This is a difficult linguistic distinction even for humans, in my perception. Also, there is an overlap. status includes the progress of an operating which already is covered semantically by state as "the current condition".
Suggested change
| | **state** | The current condition of an object, account, or operation. | A requested setting; use **policy** or **configuration**. | | |
| | **status** | The result or progress of an operation, especially a transfer. | Every kind of state. Use the exact enum name when one exists. | | |
| | **state** | The current condition of an object, account, or operation. | A requested setting; use **policy** or **configuration**. | | |
| | **result** | The result of an operation, especially a transfer. | Every kind of state. Use the exact enum name when one exists. | |
| | --- | --- | --- | | ||
| | **state** | The current condition of an object, account, or operation. | A requested setting; use **policy** or **configuration**. | | ||
| | **status** | The result or progress of an operation, especially a transfer. | Every kind of state. Use the exact enum name when one exists. | | ||
| | **mode** | A selected implementation or operating configuration, such as a VFS mode. | A temporary result or transfer status. | |
| | **policy** | A rule or preference that controls what should happen, such as pinning or keeping a file downloaded. | Proof that the requested result has already happened. | | ||
| | **configuration** | Values that select or set up how a component operates. | A live operation result. | | ||
| | **error** | A failure or failure result. | A conflict or warning unless the code treats it as an error. | | ||
| | **conflict** | A specific sync outcome where changes cannot be applied together automatically. | A general failure. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | **conflict** | A specific sync outcome where changes cannot be applied together automatically. | A general failure. | | |
| | **conflict** | A specific sync outcome where diverging changes between different content states cannot be reconciled automatically or without data loss. | A general failure. | |
| | **materialized** | An item in File Provider's local materialized set. This can include a downloaded file or a visited directory. | | ||
| | **downloaded** | The local file-content flag used for a File Provider file. | | ||
| | **visitedDirectory** | A directory that has been enumerated locally; it does not mean the directory was downloaded. | | ||
| | **dataless** | A File Provider item with no local materialized content, typically after eviction. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | **dataless** | A File Provider item with no local materialized content, typically after eviction. | | |
| | **dataless** | A File Provider item without actual content but metadata available locally. | |
| | **downloaded** | The local file-content flag used for a File Provider file. | | ||
| | **visitedDirectory** | A directory that has been enumerated locally; it does not mean the directory was downloaded. | | ||
| | **dataless** | A File Provider item with no local materialized content, typically after eviction. | | ||
| | **evict** | Removing an item's local File Provider representation without treating it as a server deletion. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | **evict** | Removing an item's local File Provider representation without treating it as a server deletion. | | |
| | **evict** | Remove the local content copy of a file provider item without actually deleting the item on the server and retain the existing metadata. | |
| | **visitedDirectory** | A directory that has been enumerated locally; it does not mean the directory was downloaded. | | ||
| | **dataless** | A File Provider item with no local materialized content, typically after eviction. | | ||
| | **evict** | Removing an item's local File Provider representation without treating it as a server deletion. | | ||
| | **keepDownloaded** | The stored intent behind “Always keep downloaded”; it is not the current downloaded or materialized state. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | **keepDownloaded** | The stored intent behind “Always keep downloaded”; it is not the current downloaded or materialized state. | | |
| | **keepDownloaded** | The stored content policy behind the “Always keep downloaded” custom file provider action; it is not a state detail. | | |
| | **content policy** | Defines how the File Provider framework is expected to handle local content copies of a file provider item. Defines policy for automatic eviction by the framework but also whether content should be downloaded from the server automatically and eagerly or local content copies evicted on case of server-side changes to the represented item. | |
|
|
||
| | Standard sync engine | File Provider engine | Notes | | ||
| | --- | --- | --- | | ||
| | virtual file / placeholder | File Provider item | Both are local representations, but `item` is the framework object. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | virtual file / placeholder | File Provider item | Both are local representations, but `item` is the framework object. | | |
| | virtual file / placeholder | File Provider item | Both are local representations, but `item` is the actual framework object regardless off its state (either "dataless" or "materialized"), not a placeholder. | |
| | **folder** | A user-facing or sync-folder concept. | | ||
| | **delete** | A deletion operation. | | ||
| | **soft-deleted** | A record marked as deleted but not yet removed. | | ||
| | **evict** | A provider or operating-system eviction operation. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | **evict** | A provider or operating-system eviction operation. | | |
| | **evict** | A File Provider framework eviction operation. | |
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.
Summary
Particularly relevant for AI agents which tend to produce incomprehensible word salads
Checklist
AI (if applicable)