CDRIVER-3054 Revise docs from mongoc_collection_(remove|insert|update) (#1783)

* recommend `mongoc_collection_remove` as an alternative to `mongoc_collection_delete`
* replace "Superseded by" to avoid suggesting functions are obsolete.
* remove internal comments redundant with public docs.
* simplify `test_update` and test a replacement document can be passed
* add missing `mongoc_init` and `mongoc_cleanup`

Author: kevinAlbs

src/libmongoc/doc/mongoc_collection_delete.rst

@@ -6,7 +6,7 @@ mongoc_collection_delete()
 .. warning::
    .. deprecated:: 1.9.0
 
-      Use :symbol:`mongoc_collection_delete_one()` or :symbol:`mongoc_collection_delete_many()` instead.
+      Use :symbol:`mongoc_collection_remove`, :symbol:`mongoc_collection_delete_one()` or :symbol:`mongoc_collection_delete_many()` instead.
 
 Synopsis
 --------

src/libmongoc/doc/mongoc_collection_insert.rst

@@ -27,7 +27,9 @@ Parameters
 Description
 -----------
 
-Superseded by :symbol:`mongoc_collection_insert_one()` and :symbol:`mongoc_collection_insert_many()`.
+.. note::
+   
+   To pass additional options, use :symbol:`mongoc_collection_insert_one()` or :symbol:`mongoc_collection_insert_many()`.
 
 This function shall insert ``document`` into ``collection``.
 

src/libmongoc/doc/mongoc_collection_remove.rst

@@ -27,7 +27,9 @@ Parameters
 Description
 -----------
 
-Superseded by :symbol:`mongoc_collection_delete_one` and :symbol:`mongoc_collection_delete_many`.
+.. note::
+   
+   To pass additional options, use :symbol:`mongoc_collection_delete_one` or :symbol:`mongoc_collection_delete_many`.
 
 This function shall remove documents in the given ``collection`` that match ``selector``. The bson ``selector`` is not validated, simply passed along as appropriate to the server.  As such, compatibility and errors should be validated in the appropriate server documentation.
 

src/libmongoc/doc/mongoc_collection_update.rst

@@ -29,7 +29,9 @@ Parameters
 Description
 -----------
 
-Superseded by :symbol:`mongoc_collection_update_one`, :symbol:`mongoc_collection_update_many`, and :symbol:`mongoc_collection_replace_one`.
+.. note::
+   
+   To pass additional options, use :symbol:`mongoc_collection_update_one`, :symbol:`mongoc_collection_update_many`, or :symbol:`mongoc_collection_replace_one`.
 
 This function shall update documents in ``collection`` that match ``selector``.
 

src/libmongoc/examples/example-update.c

@@ -3,6 +3,7 @@
 int
 main (void)
 {
+   mongoc_init ();
    bson_t *to_insert = BCON_NEW ("_id", BCON_INT32 (1));
    bson_t *selector = BCON_NEW ("_id", "{", "$gt", BCON_INT32 (0), "}");
    bson_t *update = BCON_NEW ("$set", "{", "x", BCON_INT32 (1), "}");
@@ -63,6 +64,6 @@ main (void)
    mongoc_collection_destroy (coll);
    mongoc_uri_destroy (uri);
    mongoc_client_destroy (client);
-
+   mongoc_cleanup ();
    return EXIT_SUCCESS;
 }

src/libmongoc/src/mongoc/mongoc-collection.c

@@ -1935,31 +1935,6 @@ mongoc_collection_insert_many (mongoc_collection_t *collection,
    RETURN (ret);
 }
 
-/*
- *--------------------------------------------------------------------------
- *
- * mongoc_collection_update --
- *
- *       Updates one or more documents matching @selector with @update.
- *
- * Parameters:
- *       @collection: A mongoc_collection_t.
- *       @flags: The flags for the update.
- *       @selector: A bson_t containing your selector.
- *       @update: A bson_t containing your update document.
- *       @write_concern: The write concern or NULL.
- *       @error: A location for an error or NULL.
- *
- * Returns:
- *       true if successful; otherwise false and @error is set.
- *
- * Side effects:
- *       @collection->gle is setup, depending on write_concern->w value.
- *       @error is setup upon failure.
- *
- *--------------------------------------------------------------------------
- */
-
 bool
 mongoc_collection_update (mongoc_collection_t *collection,
                           mongoc_update_flags_t uflags,
@@ -2363,38 +2338,6 @@ mongoc_collection_save (mongoc_collection_t *collection,
 }
 
 
-/*
- *--------------------------------------------------------------------------
- *
- * mongoc_collection_remove --
- *
- *       Delete one or more items from a collection. If you want to
- *       limit to a single delete, provided MONGOC_REMOVE_SINGLE_REMOVE
- *       for @flags.
- *
- *       Superseded by mongoc_collection_delete_one/many.
- *
- * Parameters:
- *       @collection: A mongoc_collection_t.
- *       @flags: the delete flags or 0.
- *       @selector: A selector of documents to delete.
- *       @write_concern: A write concern or NULL. If NULL, the default
- *                       write concern for the collection will be used.
- *       @error: A location for an error or NULL.
- *
- * Returns:
- *       true if successful; otherwise false and error is set.
- *
- *       If the write concern does not dictate checking the result, this
- *       function may return true even if it failed.
- *
- * Side effects:
- *       @collection->gle is setup, depending on write_concern->w value.
- *       @error is setup upon failure.
- *
- *--------------------------------------------------------------------------
- */
-
 bool
 mongoc_collection_remove (mongoc_collection_t *collection,
                           mongoc_remove_flags_t flags,

src/libmongoc/tests/test-mongoc-collection.c

@@ -1023,83 +1023,63 @@ test_decimal128 (void *ctx)
 static void
 test_update (void)
 {
-   mongoc_collection_t *collection;
-   mongoc_database_t *database;
-   mongoc_client_t *client;
-   bson_context_t *context;
    bson_error_t error;
-   bool r;
-   bson_oid_t oid;
-   unsigned i;
-   bson_t b;
-   bson_t q;
-   bson_t u;
-   bson_t set;
-
-   client = test_framework_new_default_client ();
-   ASSERT (client);
-
-   database = get_test_database (client);
-   ASSERT (database);
-
-   collection = get_test_collection (client, "test_update");
-   ASSERT (collection);
-
-   context = bson_context_new (BSON_CONTEXT_NONE);
-   ASSERT (context);
-
-   for (i = 0; i < 10; i++) {
-      bson_init (&b);
-      bson_oid_init (&oid, context);
-      bson_append_oid (&b, "_id", 3, &oid);
-      bson_append_utf8 (&b, "utf8", 4, "utf8 string", 11);
-      bson_append_int32 (&b, "int32", 5, 1234);
-      bson_append_int64 (&b, "int64", 5, 12345678);
-      bson_append_bool (&b, "bool", 4, 1);
-
-      ASSERT_OR_PRINT (mongoc_collection_insert_one (collection, &b, NULL, NULL, &error), error);
-
-      bson_init (&q);
-      bson_append_oid (&q, "_id", 3, &oid);
 
-      bson_init (&u);
-      bson_append_document_begin (&u, "$set", 4, &set);
-      bson_append_utf8 (&set, "utf8", 4, "updated", 7);
-      bson_append_document_end (&u, &set);
-
-      ASSERT_OR_PRINT (mongoc_collection_update (collection, MONGOC_UPDATE_NONE, &q, &u, NULL, &error), error);
+   mongoc_client_t *client = test_framework_new_default_client ();
+   mongoc_collection_t *coll = get_test_collection (client, "test_update");
 
-      bson_destroy (&b);
-      bson_destroy (&q);
-      bson_destroy (&u);
+   // Test a successful update:
+   {
+      mongoc_collection_drop (coll, NULL);
+      bson_t *b = tmp_bson ("{'foo' : 'bar'}");
+      ASSERT_OR_PRINT (mongoc_collection_insert_one (coll, b, NULL, NULL, &error), error);
+
+      bson_t *q = tmp_bson ("{}");
+      bson_t *u = tmp_bson ("{'$set': {'foo': 'updated' }}");
+      ASSERT_OR_PRINT (mongoc_collection_update (coll, MONGOC_UPDATE_NONE, q, u, NULL, &error), error);
+
+      bson_t *f = tmp_bson ("{'foo': 'updated'}");
+      int64_t count = mongoc_collection_count_documents (coll, f, NULL, NULL, NULL, &error);
+      ASSERT_OR_PRINT (count >= 0, error);
+      ASSERT_CMPINT64 (count, ==, 1);
    }
 
-   bson_init (&q);
-   bson_init (&u);
-   BSON_APPEND_INT32 (&u, "abcd", 1);
-   BSON_APPEND_INT32 (&u, "$hi", 1);
-   r = mongoc_collection_update (collection, MONGOC_UPDATE_NONE, &q, &u, NULL, &error);
-   ASSERT (!r);
-   ASSERT (error.domain == MONGOC_ERROR_COMMAND);
-   ASSERT (error.code == MONGOC_ERROR_COMMAND_INVALID_ARG);
-   bson_destroy (&q);
-   bson_destroy (&u);
+   // Test an invalid update document with both $-prefixed and non-$-prefixed fields:
+   {
+      bson_t *q = tmp_bson ("{}");
+      bson_t *u = tmp_bson ("{'abcd': 1, '$hi': 1 }");
+      bool ok = mongoc_collection_update (coll, MONGOC_UPDATE_NONE, q, u, NULL, &error);
+      ASSERT (!ok);
+      ASSERT_ERROR_CONTAINS (error, MONGOC_ERROR_COMMAND, MONGOC_ERROR_COMMAND_INVALID_ARG, "Invalid key");
+   }
 
-   bson_init (&q);
-   bson_init (&u);
-   BSON_APPEND_INT32 (&u, "" /* empty key */, 1);
-   r = mongoc_collection_update (collection, MONGOC_UPDATE_NONE, &q, &u, NULL, &error);
-   ASSERT (!r);
-   ASSERT (error.domain == MONGOC_ERROR_COMMAND);
-   ASSERT (error.code == MONGOC_ERROR_COMMAND_INVALID_ARG);
-   bson_destroy (&q);
-   bson_destroy (&u);
+   // Test an invalid update document with an empty field:
+   {
+      bson_t *q = tmp_bson ("{}");
+      bson_t *u = tmp_bson ("{'': 1 }");
+      bool ok = mongoc_collection_update (coll, MONGOC_UPDATE_NONE, q, u, NULL, &error);
+      ASSERT (!ok);
+      ASSERT_ERROR_CONTAINS (error, MONGOC_ERROR_COMMAND, MONGOC_ERROR_COMMAND_INVALID_ARG, "empty key");
+   }
 
-   ASSERT_OR_PRINT (mongoc_collection_drop (collection, &error), error);
+   // Test a successful replacement:
+   {
+      mongoc_collection_drop (coll, NULL);
+      bson_t *b = tmp_bson ("{'foo' : 'bar'}");
+      ASSERT_OR_PRINT (mongoc_collection_insert_one (coll, b, NULL, NULL, &error), error);
+
+      bson_t *q = tmp_bson ("{}");
+      bson_t *u = tmp_bson ("{'foo2': 'bar2'}");
+      ASSERT_OR_PRINT (mongoc_collection_update (coll, MONGOC_UPDATE_NONE, q, u, NULL, &error), error);
+
+      bson_t *f = tmp_bson ("{'foo2': 'bar2'}");
+      int64_t count = mongoc_collection_count_documents (coll, f, NULL, NULL, NULL, &error);
+      ASSERT_OR_PRINT (count >= 0, error);
+      ASSERT_CMPINT64 (count, ==, 1);
+      ASSERT_OR_PRINT (mongoc_collection_drop (coll, &error), error);
+   }
 
-   mongoc_collection_destroy (collection);
-   mongoc_database_destroy (database);
-   bson_context_destroy (context);
+   mongoc_collection_destroy (coll);
    mongoc_client_destroy (client);
 }