API page: http://api.drupal.org/api/drupal/modules--taxonomy--taxonomy.module/func...
Describe the problem you have found:
Me as a developer and module writer who has to write imports, also for taxonomy would like to have either a) a taxonomy_get_term_template($vid) which returns me a term object which I can modify and then save with taxonomy_term_save($term) or b) a documentation what a minimum term object looks like. This information should be imho in the taxonomy_term_save() PhpDoc and not hidden somewhere in the code.
Comment | File | Size | Author |
---|---|---|---|
#9 | 1162226-taxonomy-term-save-docs.patch | 2.14 KB | mr.baileys |
#3 | 0001-Issue-1162226-Term-object-documentation-for-taxonomy.patch | 2.11 KB | mr.baileys |
Comments
Comment #1
jhodgdonAgreed on (b). The $term documentation should document what a $term object is.
Needs to be done in D8 and backported to d7.
Comment #2
mr.baileysWorking on a patch for this.
Comment #3
mr.baileysComment #4
ro-no-lo CreditAttribution: ro-no-lo commented@mr.baileys: Your return value is nicly described, but useless information, because the object is not a reference parameter. So you'll not get the $term->tid back from that function. Only the NEW or UPDATED information.
Comment #5
mr.baileys@foobar3000: that's incorrect. Although it's an oversimplification (http://mjtsai.com/blog/2004/07/15/php-5-object-references/), you can say that PHP passes objects by reference. So $term is (kind of) passed by reference, and the object itself is altered.
If you don't believe me, run the following snippet:
Comment #6
ro-no-lo CreditAttribution: ro-no-lo commentedOkay, I thought the & Operator is still needed. Well that solves another problem that I had.
http://ideone.com/DHsVL .. looks great.
Comment #7
jhodgdonThis is a good start, but there are a number of spelling/grammar/style problems that need fixing:
a) Spelling errors: ommitted/ommitting should have only one m.
b) - format: (optional) The filter format for the term's description.
I don't think we call them "filter format" in D7/8?
c) - tid: (optional) The unique id ...
"id" is a psychological term. "ID" is an abbreviation for identifier. Also, further down in the text, please don't use "tid". Use "term ID".
d) parent: (optional) The parent term(s) for this term. This can be a single tid, an array of tids, or an array of arrays containing tids.
What does an array of arrays do? I don't understand what that would mean for what the parents are? Please add an explanation.
e) Since a taxonomy term is an entity, any fields contained in term object ...
Needs "the" in "any fields contained in the term object"
f) + * Status constant indicating if term was inserted (SAVED_NEW) or updated
Should be:
A status constant indicating whether the term was ...
g) + * of the newly creating term.
creating -> created
Comment #8
jhodgdonAlso, looking at the code for taxonomy_term_save, I'm seeing additional components to $term being used:
$term->vocabulary_machine_name
$term->original
(and maybe others)
So please go through the function and make sure everything is in the doc. Thanks!
Comment #9
mr.baileysThanks for the detailed feedback! Patch attached should address all the issues raised.
It seems that the support for nested arrays is a remnant of the early days and no longer used (I've opened #1175156: Tests for $term->parent in Term::save() to address this). I've removed this part about an array of arrays from the documentation.
For $term->original, this does not seem to be used by core itself, neither is it documented in any of the taxonomy hooks, so I'm not entirely sure what, if any, use it has.
Comment #10
jhodgdonI beg to differ... At least, $term->original is read and then if missing, set in taxonomy_term_save(). I think it should be documented, even if core isn't using it. Either that or it should be removed from taxonomy_term_save(). It is loading it using entity_load_unchanged(), so it seems it is the previous version of the taxonomy term -- let's document it as that. Oh I see -- you did document it. Good. :)
Anyway, I double-checked all the components listed here and I agree with the list and the descriptions. Nice work!
Let's get this into 8.x/7.x.
Comment #11
Dries CreditAttribution: Dries commentedCommitted to 7.x and 8.x. Thanks!