Skip to content
This repository has been archived by the owner on Feb 12, 2024. It is now read-only.

docs: clarify that mtime and mode are optional #3302

Merged
merged 2 commits into from
Oct 27, 2020
Merged

docs: clarify that mtime and mode are optional #3302

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3e0ae74
docs: clarify that mtime and mode are optional
lidel Sep 24, 2020
4c85568
docs: clarify implcit values and link to specs
achingbrain Oct 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/core-api/FILES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,9 +125,9 @@ The regular, top-level API for add, cat, get and ls Files on IPFS
path?: string
// The contents of the file (see below for definition)
content?: FileContent
// File mode to store the entry with (see https://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation)
// (Optional) mode to store the entry with (see https://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation)
mode?: number | string
// The modification time of the entry (see below for definition)
// (Optional) modification time of the entry (see below for definition)
mtime?: UnixTime
}
```
Expand Down Expand Up @@ -180,7 +180,7 @@ An optional object which may have the following keys:
| -------- | -------- |
| `Promise<UnixFSEntry>` | A object describing the added data |

Each yielded object is of the form:
Each yielded object is of the form (`mtime` and `mode` are optional, so may be missing):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mode has a default value so shouldn't be missing.

https://github.com/ipfs/specs/blob/master/UNIXFS.md#metadata

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@achingbrain Ack, I was unaware of implicit mode default.
This complicates things a bit.. would this work?

Suggested change
Each yielded object is of the form (`mtime` and `mode` are optional, so may be missing):
Each yielded object is of the form (with optional `mtime` and custom/implicit `mode` [metadata](https://github.com/ipfs/specs/blob/master/UNIXFS.md#metadata)):

If not, we could just leave this line as it was before. Let me know.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps reverting this and just adding a comment in the JS object below would be helpful? Additionally, keeping the optional ? indicator on the key is a nice way to represent the potential missing response value.

{
  path: '/tmp/myfile.txt',
  cid: CID('QmHash'),
  mode: Number, // implicit if not provided
  mtime?: { secs: Number, nsecs: Number }, // may be missing
  size: 123
}


```JavaScript
{
Expand Down Expand Up @@ -262,7 +262,7 @@ An optional object which may have the following keys:
| -------- | -------- |
| `AsyncIterable<UnixFSEntry>` | An async iterable that yields objects describing the added data |

Each yielded object is of the form:
Each yielded object is of the form (`mtime` and `mode` are optional, so may be missing):

```JavaScript
{
Expand Down