Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Title says it all, patch attached, part of the meta-issue to make sure all hooks are documented
Comment | File | Size | Author |
---|---|---|---|
#13 | 727282-moreexplanation.patch | 2.13 KB | jhodgdon |
#6 | 727282.patch | 1.93 KB | gdd |
#3 | 727282.patch | 1.93 KB | gdd |
hook_filetransfer_backends_docs.patch | 1.96 KB | gdd | |
Comments
Comment #1
Dries CreditAttribution: Dries commentedDo we need the
|| ini_get('allow_url_fopen')
in the example? Sounds a litte messy.Comment #2
jhodgdonA few minor issues with the doc as well:
a)
extraneous . at start of that line, and it should end with :
b) I don't think backend is a word. How about back ends?
c) Do you want to explain what a "file transfer back end" is? I didn't find that information in the doc, and have no idea, except that in the @return section it mentioned "mechanisms", which makes more sense to me... But a couple of lines saying "The update system uses file transfer back ends to..." and/or "A file transfer back end is .... For example, ..." might help.
d)
This key is settings_form not settings-form in the code example.
e) Dries's comment -- I think it comes from the real code, but I kind of agree it doesn't illuminate much as an example.
Comment #3
gddI agree that 'backend' is confusing, but since it is was the code uses, it is what I used. I shouldn't get into a long explanation of it here IMO, the @see references provide far more complete detail for those who need it.
The allow_furl_open in the example was in fact from the original code but I'm happy to pull it out.
Comment #5
jhodgdonHow about "file transfer mechanisms" rather than "file transfer backends" for the one-liner doc? That is clearer to me -- and I really want one-liners to be clear. There is a mix of "mechanism" and "backend" in the doc, which I don't like... Stick to one or the other (preferably "mechanism" unless you can demonstrate that "backend" is ubiquitously used in the industry for this purpose -- I have never seen it before and didn't immediately know what it meant). Just because the name of the function uses "backend" doesn't mean that the doc should also use it, if it's not a standard term that everyone would immediately understand.
Also, it looks like this function can return more than one backend/mechanism, so in @return it should say "mechanisms" being provided.
keys. -> keys:
One more very small nitpick:
Either add "the" before title or remove "the" before name, for parallelism. :)
Comment #6
gddIt seems silly to me to be referring to mechanisms when everything in the hook title and the actual sample code refers to backends. For instance the doc would read
whereas in the code sample it is
IE obviously the title is associated with an array $backends. While I agree that this is a possibly terrible name, I feel like two ways to refer to the same thing may engender more confusion. We should refer to it consistently. So attached is a patch which actually removes all references to mechanism and replaces them with backend, plus the other tweaks requested.
Comment #7
gddComment #8
moshe weitzman CreditAttribution: moshe weitzman commentedMechanism is even less clear than backend to me. At least backend implies no UI. Mechanism could be anything.
Comment #9
jhodgdonOK... Could we then explain exactly what a "backend" is in the doc? The first time I read through that doc I had zero idea what in the world a "backend" was until I saw in the example that FTP was a backend, and then I had an inkling. Maybe a sentence in the main function doc explaining what a "file transfer backend" is, and what it would be used for?
And is this an industry-standard term? If not, I still think it should be "back ends" not "backends", which is not an English word. Unless you can assure me that this is the standard term in use outside of this Drupal API.
Comment #10
moshe weitzman CreditAttribution: moshe weitzman commentedI mean no malice here: http://lmgtfy.com/?q=backend&l=1
Comment #11
jhodgdonWhen I google "file transfer backend" (without the quotes), the first hit's page title is "file transfer back-end" from ubuntu.com.
The next one that's not a forum uses "back end".
There are also some that use "backend" in the first page of results.
I wouldn't say there's any consistency.
Comment #12
jhodgdonMeanwhile, whether we use back end, back-end, or backend, I still think the doc could explain what the back-end is going to be used for, what it is, etc. Which the latest proposal doesn't do.
And if you want to standardize on "backend" for Drupal, whatever, though I don't think it's in any way consistent.
BTW, the first 4 hits when I google just "backend" use "back-end", so I'm not sure what you were trying to say there moshe.
Comment #13
jhodgdonOK. Let's standardize on backends, I'm convinced enough.
Here's a new patch with a bit more explanation.
Comment #14
gddLooks good to me.
Comment #15
webchickGreat work, folks!
Committed to HEAD.