docs: remove array arguments and document missing options #277
Conversation
ghost
assigned 
SPEC/FILES.md
Outdated
|
|
||
| If no `callback` is passed, a promise is returned. | ||
|
|
||
| **Example:** | ||
|
|
||
| ```JavaScript | ||
| ipfs.files.cp(['/src-file', '/dst-file'], (err) => { | ||
| ipfs.files.cp('/src-file', '/dst-file', (err) => {s |
There was a problem hiding this comment.
There's a trailing "s" here
SPEC/FILES.md
Outdated
| - `from` is the path of the source file to copy. | ||
| - `to` is the path of the destination file to copy to. | ||
| - `from` is the path(s) of the source to copy. It might be: | ||
| - An existing MFS path (e.g. `/my-dir/my-file.txt`) |
There was a problem hiding this comment.
A note or example to clarify that from can be a file or a directory would be good here.
| #### `files.cp` | ||
|
|
||
| > Copy files. | ||
|
|
||
| ##### `Go` **WIP** | ||
|
|
||
| ##### `JavaScript` - ipfs.files.cp([from, to], [callback]) | ||
| ##### `JavaScript` - ipfs.files.cp(...from, to, [options], [callback]) |
There was a problem hiding this comment.
I can't claim it, it's stolen from cp..
SPEC/FILES.md
Outdated
| - `hash` is a Boolean value to return only the hash (default: false) | ||
| - `size` is a Boolean value to return only the size (default: false) | ||
| - `withLocal` is a Boolean value to compute the amount of the dag that is local, and if possible the total size (default: false) | ||
| - `callback` is an optional function with the signature `function (error, stats) {}`, where `error` may be an Error that occured if the operation was not successful and `stat` is an Object with the following keys: |
There was a problem hiding this comment.
The name of the result parameter changes! Needs an add "s" to stat or remove an "s" from stats in function (error, stats) {}.
SPEC/FILES.md
Outdated
| @@ -738,19 +765,20 @@ ipfs.files.rm('/my/beautiful/directory', { recursive: true }, (err) => { | |||
|
|
|||
| Where: | |||
|
|
|||
| - `path` is the path of the file to read. | |||
| - `path` is the path of the file to read and must point to a file | |||
There was a problem hiding this comment.
Adding "not a directory" to the end of that sentence would make it clearer - I think that's what you mean? (also for readPullStream and readReadableStream please!)
SPEC/FILES.md
Outdated
| } | ||
| }) | ||
|
|
||
| ipfs.files.cp('/src-dir', '/dst-dir', (err) => {s |
There was a problem hiding this comment.
It would be helpful for the reader if the difference between this example and the one above was highlighted e.g. // To copy a directory - I thought it was a duplication when I first glanced at it 😉
There was a problem hiding this comment.
For copying a single file, the destination must not exist, but for copying a single directory or multiple files/directories the destination needs to exist and be a directory (or the parents option needs to be passed to create the destination directory and any parents).
If that's right(?), it's really useful info that should be mentioned alongside "If there are multiple sources..." above (or something to that effect!).
There was a problem hiding this comment.
These changes will need to be applied to mv also as it has got a similar API.
There was a problem hiding this comment.
There's also that trailing "s" again.
|
@alanshaw I've updated the docs around |
chore: update method signatures in line with ipfs-inactive/interface-js-ipfs-core#277
Further to the conversation on #262 I've swept the mfs api and made what I hope are improvements to consistency and added flags and options where I've found them undocumented in the codebase or where they were otherwise missing.
Most of this has been implemented in ipfs/js-ipfs-mfs.