taxonomy_term_save should document what is in a $term object

Agreed on (b). The $term documentation should document what a $term object is.

Needs to be done in D8 and backported to d7.

Working on a patch for this.

@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:

$term = new stdClass;

$term->vid = 1;
$term->name = 'My Tag';

$status = taxonomy_term_save($term);

print_r($term->tid);

This 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

Also, 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!

Thanks for the detailed feedback! Patch attached should address all the issues raised.

What does an array of arrays do? I don't understand what that would mean for what the parents are? Please add an explanation.

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.

I 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.

Committed to 7.x and 8.x. Thanks!