taxonomy_vocabulary_save documentation needs clarification: new vocabulary versus updating vocabulary

Good idea on the documentation. We don't provide examples in the docs though -- you can add one as a comment, or try one of the "functions that call this function" for an actual usage example.

This is a 7.x issue only, by the way. It's totally changed in 8.x apparently.

Probably a good Novice project to fix this... there's also a typo in the @return section -- missing a space in "updated(SAVED_UPDATED)".

I got this(assigned to myself).
Also, you want me to put note or something on the api documentation.
http://api.drupal.org/api/drupal/modules!taxonomy!taxonomy.module/functi...

Needless to say, thank you all you do "jhodgdon"

Yes, you need to modify the documentation header for the taxonomy_vocabulary_save() function, to add information about what to do to save a new vocabulary vs. updating an existing vocabulary.

See
http://drupal.org/novice (instructions on how to contribute a patch)
http://drupal.org/node/1354 (standards for documentation headers)

Remove the vid parameter(auto_increment field) which is neither mandatory nor optional for the function call.
When you call the function with the other mandatory parameters, "vid" is auto generated for you.
I also, took care of the space issue mentioned in comment#1
see Patch attached.

Thanks! But... I think if you save an existing vocabulary, you need the 'vid' property to be set?

The function name being "taxonomy_vocabulary_save($vocabulary)", it could be very confusing.
Right now it appears as follow which looks like mandatory:
vid: The ID of the vocabulary.
Would you rather leave it there, but add some comments? such as:

vid: The ID of the vocabulary(to be used to update existing vocabulary only).

Yes, something like #6 would be good.

Done (see patch).

Looks good! Maybe it needs "an" in there: "(used to update *an* existing vocabulary only)"? And the original report here stated that you *can't* have 'vid' if you are saving a new vocabulary, so maybe this point could be made a little more strongly?

Sure, i added the change requested.

What I meant in #10 about "more strongly" making the point was that we should change the text on the 'vid' entry to say something like: "Omit if creating a new vocabulary", because this was not clear to the person who originally filed this issue. The current text says it is only *used* if you are updating an existing vocabulary, but apparently you get an error when creating a new one if the vid is present, so we need to make the point more strongly, I think?

How does this look

Better! This is definitely much more clear. There are a couple of typographical/grammatical type issues with this though:

- *   - vid: The ID of the vocabulary.
+ *   - vid: The ID of the vocabulary (Omit if creating a new vocabulary e.g. only use to update existing vocabulary).

- Omit should not be capitalized.
- e.g. does not make sense here (e.g. == "for example"). I think maybe e.g. could be replaced by a semi-colon (;).
- At the end of the line, it should say "an existing" ("an" is missing).
- The line goes longer than 80 characters, and needs to be wrapped.

changes made. Thanks

Thanks! Looks good except that there is an extra space at the end of this line:

+ *   - vid: The ID of the vocabulary (omit if creating a new vocabulary; only 

I removed the space. Take a look. Thanks

One more thing, which changed since the last patch -- we need a space before the ( in:
* - vid: The ID of the vocabulary(omit if creating a new vocabulary; only

reintroduced the space before the parenthesis.

Thanks @trogels! I reviewed the patch and it looks mostly correct.

+++ b/modules/taxonomy/taxonomy.moduleundefined
@@ -386,7 +386,8 @@ function taxonomy_admin_vocabulary_title_callback($vocabulary) {
+ *   - vid: The ID of the vocabulary (omit if creating a new vocabulary; only
+ *     use to update an existing vocabulary).

This comment looks correct to me. However, our API documentation standards indicate that optional parameters should have (optional) before the description and after the key name. Reference: http://drupal.org/node/1354#lists

Let's create a new patch with the (optional) in addition to the current comment change.

I see. It's fixed. I included an interdiff aswell and wrapped the line since it exceeded 80 characters.

That's the correct fix. Thanks!

Thank you. Committed to 7.x.