reformatting and minor corrections to webapi.rst; remove a reference to the test grid

[davidsarah]

Reflow, change tabs to spaces, and make some minor corrections (see the third patch in the patchset).

[davidsarah]

docs/frontends/webapi.txt: clean up formatting (reflo, tabs->spaces); minor corrections; remove reference to test grid

[davidsarah]

This needs rebasing.

[marlowe]

DS,

Would it be helpful for me to do the rebasing for this ticket?

Patrick

[warner]

marlowe: yeah, that'd be great. I'd suggest just walking through davidsarah's diff in one window and applying the suggested changes by hand to the current trunk, then looking around for other instances of the same sorts of changes (i.e. search for tabs and fix them all). I wouldn't be surprised if the original diff doesn't apply cleanly after all this time: it calls for a human touch.

thanks!

[davidsarah]

Please do, thanks.

[davidsarah]

Could you also please apply this patch:

[[1.9.2 branch] Add comments and a caveat in webapi.rst indicating that
the needs-rebalancing field may be computed incorrectly. refs #1115 refs
#1784
david-sarah@jacaranda.org**20120701230843
 Ignore-this: fd2939ae4291207978dc463a2ad92d1b
] {
hunk ./docs/frontends/webapi.rst 1350
-                            shares
+                            shares. Note that a high value does not
necessarily
+                            imply good share distribution, because some of
+                            these servers may only hold duplicate shares.
hunk ./docs/frontends/webapi.rst 1367
-    needs-rebalancing: (bool) True if there are multiple shares on a single
-                       storage server, indicating a reduction in
reliability
-                       that could be resolved by moving shares to new
-                       servers.
+    needs-rebalancing: (bool) This field is intended to be True iff
+                       reliability could be improved for this file by
+                       rebalancing, i.e. by moving some shares to other
+                       servers. It is not guaranteed to be computed
correctly
+                       in Tahoe-LAFS up to and including v1.9.2, and its
+                       precise definition may change in future versions.
hunk ./src/allmydata/immutable/checker.py 799
+        # TODO: this may be wrong, see ticket #1115 comment:27 and
ticket #1784.
hunk ./src/allmydata/immutable/filenode.py 134
+
+                    # TODO: this may be wrong, see ticket #1115
comment:27 and ticket #1784.
}

Thanks.

[daira]

Just the part of the patch that applies to webapi.rst, I meant.

[zooko]

Since this ticket was opened, the test grid has been revived by PRabahy. Does that mean this doc should be adjusted to once again refer to the test grid?

Whatever we do, we should do it soon! Brian will be making an RC1 release of Tahoe-LAFS v1.10.0 soon, and it would be good for these docs to go into that so people can test the docs.

[Daira Hopwood <david-sarah@…>]

In b06f8cd8d03a6239:

Add comments and a caveat in webapi.rst indicating that
the needs-rebalancing field may be computed incorrectly. refs #1115, #1784, #1477

Signed-off-by: Daira Hopwood <david-sarah@…>

[daira]

Also in 6899d028540fbd4f. I just dropped the formatting changes; I don't think they're important.