Improve Name.Bound documentation. #378
Conversation
The 'id' and 'path' fields of Name.Bound were insufficiently documented. Now the documentation clarifies that 'path' should only contain unbound residual path components and that 'id' should only reflect the bound path.
|
Fixes #376 |
|
pulling in, thanks for the docs! |
| @@ -39,7 +39,11 @@ object Name { | |||
| * | |||
| * Equality of two Names is delegated to `id`. Two Bound instances | |||
| * are equal whenever their `id`s are. `id` identifies the `addr` | |||
| * and not the `path`. | |||
| * and not the `path`. If the `id` is a [[com.twitter.finagle.Name.Path | |||
| * Path]], it should only contain *bound*--not residual--path components. | |||
There was a problem hiding this comment.
do we ever define what residual means?
There was a problem hiding this comment.
er, to be more precise, I don't know what a residual path is. Can we add a description of what a residual path is, and what it might be used for?
There was a problem hiding this comment.
I was hoping bound and unbound were the operative words and residual was simply an adjective. Basically, given a path like /s/buoyant/proxy/s/svc/app/path/to/resource, a Namer may only bind a prefix like /s/buoyant/proxy and leave the residual path, /s/svc/app/path/to/resource to be bound later (i.e. by the proxy). When the proxy binds the remaining name, it may only bind /s/svc/app, leaving /path/to/resource to be handled by the application in whatever way it deems fit.
I'll try to figure out the best way to fit this into the docs.
|
For future reference, it would be rad if you included the Problem / Solution / Result in the commit message directly, since we just snarf your commit message in directly with a signed-off-by message. |
|
Sorry, it was in there just without the words 'problem' and 'solution' On Tue, May 5, 2015 at 12:48 PM, Moses Nakamura notifications@github.com
Oliver Gould ver@buoyant.io |
|
No worries! |
| * Path]], it should only contain *bound*--not residual--path components. | ||
| * | ||
| * The `path` contains unbound residual path components that were not | ||
| * processed duing name resolution. |
|
I'd like it better if we included @olix0r's description of residual paths but I think the posted version is still an improvement for experts/people who know the jargon so I'm happy to have it land. |
|
sorry i haven't popped stack back to this yet. i can address this tomorrow |
|
I added a note about why residual paths are even a thing. Let me know if it needs more clarification. |
| @@ -23,6 +23,11 @@ import com.twitter.finagle.util.Showable | |||
| * (e.g. `Http.newClient(/s/org/servicename)`). These APIs use `Resolver` under | |||
| * the hood to resolve the destination names into the `Name` representation | |||
| * of the appropriate cluster. | |||
| * | |||
| * As names are are bound, a [[com.twitter.finagle.Namer Namer]] may | |||
|
lgtm modulo typo |
|
lgtm |
Problem The 'id' and 'path' fields of Name.Bound were insufficiently documented. Solution Clarify that 'path' should only contain unbound residual path components and that 'id' should only reflect the bound path. Github PR #378 Signed-off-by: Daniel Schobel <dschobel@twitter.com> RB_ID=704664
|
Closed by de6c058 |
Problem The 'id' and 'path' fields of Name.Bound were insufficiently documented. Solution Clarify that 'path' should only contain unbound residual path components and that 'id' should only reflect the bound path. Github PR twitter#378 Signed-off-by: Daniel Schobel <dschobel@twitter.com> RB_ID=704664
Problem
The 'id' and 'path' fields of Name.Bound were insufficiently documented.
Solution
Clarify that 'path' should only contain unbound residual path components and that 'id' should only reflect the bound path.