Skip to content

Commit b6879b4

Browse files
scaleway-botremyleone
scaleway-bot
and
remyleone
authored
feat(ipfs): add documentation (#3155)
Co-authored-by: Rémy Léone <[email protected]>
1 parent eb63a03 commit b6879b4

File tree

1 file changed

+62
-51
lines changed

1 file changed

+62
-51
lines changed

‎internal/namespaces/ipfs/v1alpha1/ipfs_cli.go

Lines changed: 62 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -20,50 +20,55 @@ var (
2020
func GetGeneratedCommands() *core.Commands {
2121
return core.NewCommands(
2222
ipfsRoot(),
23-
ipfsIpfs(),
23+
ipfsPin(),
2424
ipfsVolume(),
2525
ipfsVolumeCreate(),
2626
ipfsVolumeGet(),
2727
ipfsVolumeList(),
2828
ipfsVolumeUpdate(),
2929
ipfsVolumeDelete(),
30-
ipfsIpfsAddURL(),
31-
ipfsIpfsAddCid(),
32-
ipfsIpfsGetPinID(),
33-
ipfsIpfsListPins(),
34-
ipfsIpfsRmPinID(),
30+
ipfsPinCreateByURL(),
31+
ipfsPinCreateByCid(),
32+
ipfsPinGet(),
33+
ipfsPinList(),
34+
ipfsPinDelete(),
3535
)
3636
}
3737
func ipfsRoot() *core.Command {
3838
return &core.Command{
39-
Short: `Pinning service ipfs API for Scaleway`,
40-
Long: `Ipfs pinning service v1alpha1.`,
39+
Short: `IPFS Pinning service API`,
40+
Long: `IPFS Pinning service API.`,
4141
Namespace: "ipfs",
4242
}
4343
}
4444

45-
func ipfsIpfs() *core.Command {
45+
func ipfsPin() *core.Command {
4646
return &core.Command{
47-
Short: `add content by cid or url and manage pins`,
48-
Long: `add content by cid or url and manage pins.`,
47+
Short: `Manage your pins (create-by-*, delete, list by volume ID)`,
48+
Long: `A pin is an abstract object that holds a Content Identifier (CID). It is defined that during the lifespan of a pin, the CID (and all sub-CIDs) must be hosted by the service
49+
It is possible that many pins target the same CID, regardless of the user.
50+
`,
4951
Namespace: "ipfs",
50-
Resource: "ipfs",
52+
Resource: "pin",
5153
}
5254
}
5355

5456
func ipfsVolume() *core.Command {
5557
return &core.Command{
56-
Short: `manage volumes`,
57-
Long: `manage volumes.`,
58+
Short: `Manage your volumes (create, delete, list by Project ID)`,
59+
Long: `A volume is bucket of pins. It is similar to an Object Storage bucket. Volumes are useful to gather pins with similar lifespans
60+
All pins must be attached to a volume. And all volumes must be attached to a Project ID.
61+
`,
5862
Namespace: "ipfs",
5963
Resource: "volume",
6064
}
6165
}
6266

6367
func ipfsVolumeCreate() *core.Command {
6468
return &core.Command{
65-
Short: `Create volume`,
66-
Long: `Create volume.`,
69+
Short: `Create a new volume from a Project ID. Volume is identified by an ID and used to host pin references`,
70+
Long: `Volume is personal (at least to your organization) even if IPFS blocks and CID are available to anyone.
71+
Should be the first command you made because every pin must be attached to a volume.`,
6772
Namespace: "ipfs",
6873
Resource: "volume",
6974
Verb: "create",
@@ -92,8 +97,8 @@ func ipfsVolumeCreate() *core.Command {
9297

9398
func ipfsVolumeGet() *core.Command {
9499
return &core.Command{
95-
Short: `Get information about volume`,
96-
Long: `Get information about volume.`,
100+
Short: `Retrieve information about a specific volume`,
101+
Long: `Retrieve information about a specific volume.`,
97102
Namespace: "ipfs",
98103
Resource: "volume",
99104
Verb: "get",
@@ -121,8 +126,8 @@ func ipfsVolumeGet() *core.Command {
121126

122127
func ipfsVolumeList() *core.Command {
123128
return &core.Command{
124-
Short: `List volumes in project-id`,
125-
Long: `List volumes in project-id.`,
129+
Short: `Retrieve information about all volumes from a Project ID`,
130+
Long: `Retrieve information about all volumes from a Project ID.`,
126131
Namespace: "ipfs",
127132
Resource: "volume",
128133
Verb: "list",
@@ -161,8 +166,8 @@ func ipfsVolumeList() *core.Command {
161166

162167
func ipfsVolumeUpdate() *core.Command {
163168
return &core.Command{
164-
Short: `Update volume name or tag`,
165-
Long: `Update volume name or tag.`,
169+
Short: `Update volume information (tag, name...)`,
170+
Long: `Update volume information (tag, name...).`,
166171
Namespace: "ipfs",
167172
Resource: "volume",
168173
Verb: "update",
@@ -202,8 +207,8 @@ func ipfsVolumeUpdate() *core.Command {
202207

203208
func ipfsVolumeDelete() *core.Command {
204209
return &core.Command{
205-
Short: `Delete volume`,
206-
Long: `Delete volume.`,
210+
Short: `Delete a volume by its ID and every pin attached to this volume. Can take a while, depending of your pinned content`,
211+
Long: `Delete a volume by its ID and every pin attached to this volume. Can take a while, depending of your pinned content.`,
207212
Namespace: "ipfs",
208213
Resource: "volume",
209214
Verb: "delete",
@@ -235,13 +240,16 @@ func ipfsVolumeDelete() *core.Command {
235240
}
236241
}
237242

238-
func ipfsIpfsAddURL() *core.Command {
243+
func ipfsPinCreateByURL() *core.Command {
239244
return &core.Command{
240-
Short: `Add content in volume by url`,
241-
Long: `Add content in volume by url.`,
245+
Short: `Create a pin request. Will fetch and store the content pointed by the provided URL. The content must be available on the public IPFS network`,
246+
Long: `The content (IPFS blocks) will be host by the pinning service until pin deletion.
247+
From that point, any other IPFS peer can fetch and host your content: Make sure to pin public or encrypted content.
248+
Many pin requests (from different users) can target the same CID.
249+
A pin is defined by its ID (UUID), its status (queued, pinning, pinned or failed) and target CID.`,
242250
Namespace: "ipfs",
243-
Resource: "ipfs",
244-
Verb: "add-url",
251+
Resource: "pin",
252+
Verb: "create-by-url",
245253
// Deprecated: false,
246254
ArgsType: reflect.TypeOf(ipfs.CreatePinByURLRequest{}),
247255
ArgSpecs: core.ArgSpecs{
@@ -288,13 +296,16 @@ func ipfsIpfsAddURL() *core.Command {
288296
}
289297
}
290298

291-
func ipfsIpfsAddCid() *core.Command {
299+
func ipfsPinCreateByCid() *core.Command {
292300
return &core.Command{
293-
Short: `Add content in volume by cid`,
294-
Long: `Add content in volume by cid.`,
301+
Short: `Create a pin request. Will fetch and store the content pointed by the provided CID. The content must be available on the public IPFS network`,
302+
Long: `The content (IPFS blocks) will be host by the pinning service until pin deletion.
303+
From that point, any other IPFS peer can fetch and host your content: Make sure to pin public or encrypted content.
304+
Many pin requests (from different users) can target the same CID.
305+
A pin is defined by its ID (UUID), its status (queued, pinning, pinned or failed) and target CID.`,
295306
Namespace: "ipfs",
296-
Resource: "ipfs",
297-
Verb: "add-cid",
307+
Resource: "pin",
308+
Verb: "create-by-cid",
298309
// Deprecated: false,
299310
ArgsType: reflect.TypeOf(ipfs.CreatePinByCIDRequest{}),
300311
ArgSpecs: core.ArgSpecs{
@@ -359,13 +370,13 @@ func ipfsIpfsAddCid() *core.Command {
359370
}
360371
}
361372

362-
func ipfsIpfsGetPinID() *core.Command {
373+
func ipfsPinGet() *core.Command {
363374
return &core.Command{
364-
Short: `Get pin id in volume`,
365-
Long: `Get pin id in volume.`,
375+
Short: `Retrieve information about the provided pin ID (not the CID): status, last modification, CID`,
376+
Long: `Retrieve information about the provided pin ID (not the CID): status, last modification, CID.`,
366377
Namespace: "ipfs",
367-
Resource: "ipfs",
368-
Verb: "get-pin-id",
378+
Resource: "pin",
379+
Verb: "get",
369380
// Deprecated: false,
370381
ArgsType: reflect.TypeOf(ipfs.GetPinRequest{}),
371382
ArgSpecs: core.ArgSpecs{
@@ -394,13 +405,13 @@ func ipfsIpfsGetPinID() *core.Command {
394405
}
395406
}
396407

397-
func ipfsIpfsListPins() *core.Command {
408+
func ipfsPinList() *core.Command {
398409
return &core.Command{
399-
Short: `List pins in specific volume`,
400-
Long: `List pins in specific volume.`,
410+
Short: `Retrieve information about all pins into a volume`,
411+
Long: `Retrieve information about all pins into a volume.`,
401412
Namespace: "ipfs",
402-
Resource: "ipfs",
403-
Verb: "list-pins",
413+
Resource: "pin",
414+
Verb: "list",
404415
// Deprecated: false,
405416
ArgsType: reflect.TypeOf(ipfs.ListPinsRequest{}),
406417
ArgSpecs: core.ArgSpecs{
@@ -458,13 +469,13 @@ func ipfsIpfsListPins() *core.Command {
458469
}
459470
}
460471

461-
func ipfsIpfsRmPinID() *core.Command {
472+
func ipfsPinDelete() *core.Command {
462473
return &core.Command{
463-
Short: `Remove by pin id`,
464-
Long: `Remove by pin id.`,
474+
Short: `Create an unpin request. If the pin was the last to target a specific CID, the content will be erase from storage`,
475+
Long: `The function is indempotent.`,
465476
Namespace: "ipfs",
466-
Resource: "ipfs",
467-
Verb: "rm-pin-id",
477+
Resource: "pin",
478+
Verb: "delete",
468479
// Deprecated: false,
469480
ArgsType: reflect.TypeOf(ipfs.DeletePinRequest{}),
470481
ArgSpecs: core.ArgSpecs{
@@ -492,8 +503,8 @@ func ipfsIpfsRmPinID() *core.Command {
492503
return nil, e
493504
}
494505
return &core.SuccessResult{
495-
Resource: "ipfs",
496-
Verb: "rm-pin-id",
506+
Resource: "pin",
507+
Verb: "delete",
497508
}, nil
498509
},
499510
}

0 commit comments

Comments
 (0)