[tahoe-lafs-trac-stream] [tahoe-lafs] #1866: Clarify url syntax at WAPI doc

[tahoe-lafs]

#1866: Clarify url syntax at WAPI doc
---------------------------+---------------------------
 Reporter:  thedod         |          Owner:  marlowe
     Type:  defect         |         Status:  new
 Priority:  normal         |      Milestone:  undecided
Component:  documentation  |        Version:  n/a
 Keywords:                 |  Launchpad Bug:
---------------------------+---------------------------
 At [https://tahoe-lafs.org/trac/tahoe-
 lafs/browser/git/docs/frontends/webapi.rst the WAPI doc] there should be a
 list of of all prefix options, followed by a list of sections describing
 each.

 /cap appears as an orphan line somewhere on the page, and it's not clear
 from the text whether we should use it and when.

 /file appears inside the /named section, and
 theres's also no mention of the variant that contains a /@@named=/
 component (the WAPI links to such urls).
 What does it mean (removing the component doesn't seem to matter)? Which
 of the 3 options (/named/ or /file/ with or without /@@named=/) is
 preferred when?

 Another thing I can't find (maybe it's on some other doc, but then
 webapi.rst should link to it): list (+ explanation) of all cap types:
 DIR2-RO, DIR2-CHK, CHK, etc. (and in general - explanation of cap uri
 syntax).
 This (or a link to it) should appear before explaining urls that *contain*
 a cap :)

-- 
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1866>
tahoe-lafs <https://tahoe-lafs.org>
secure decentralized storage