CDRIVER-2643 update docs for new GridFS impl

Author: kevinAlbs

src/libmongoc/doc/api.rst

@@ -9,6 +9,7 @@ API Reference
    logging
    errors
    lifecycle
+   gridfs
    mongoc_bulk_operation_t
    mongoc_change_stream_t
    mongoc_client_pool_t

src/libmongoc/doc/gridfs.rst

@@ -0,0 +1,10 @@
+GridFS
+======
+
+The C driver includes two APIs for GridFS.
+
+The older API consists of :symbol:`mongoc_gridfs_t` and its derivatives. It contains deprecated API, does not support read preferences, and is not recommended in new applications. It does not conform to the `MongoDB GridFS specification <https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst>`_.
+
+The newer API consists of :symbol:`mongoc_gridfs_bucket_t` and allows uploading/downloading through derived :symbol:`mongoc_stream_t` objects. It conforms to the `MongoDB GridFS specification <https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst>`_.
+
+There is not always a straightforward upgrade path from an application built with :symbol:`mongoc_gridfs_t` to :symbol:`mongoc_gridfs_bucket_t` (e.g. a :symbol:`mongoc_gridfs_file_t` provides functions to seek but :symbol:`mongoc_stream_t` does not). But users are encouraged to upgrade when possible.

src/libmongoc/doc/lifecycle.rst

@@ -26,6 +26,13 @@ You can create a :symbol:`mongoc_gridfs_t` from a :symbol:`mongoc_client_t`, cre
 
 Each of these objects depends on the object it was created from. Always destroy GridFS objects in the reverse of the order they were created. The sole exception is that a :symbol:`mongoc_gridfs_file_t` need not be destroyed before the :symbol:`mongoc_gridfs_file_list_t` it was created from.
 
+GridFS bucket objects
+---------------------
+
+Create :symbol:`mongoc_gridfs_bucket_t` with a :symbol:`mongoc_database_t` derived from a :symbol:`mongoc_client_t`. The :symbol:`mongoc_database_t` is independent from the :symbol:`mongoc_gridfs_bucket_t`. But the :symbol:`mongoc_client_t` must outlive the :symbol:`mongoc_gridfs_bucket_t`.
+
+A :symbol:`mongoc_stream_t` may be created from the :symbol:`mongoc_gridfs_bucket_t`. The :symbol:`mongoc_gridfs_bucket_t` must outlive the :symbol:`mongoc_stream_t`.
+
 Sessions
 --------
 

src/libmongoc/doc/mongoc_gridfs_bucket_t.rst

@@ -15,12 +15,18 @@ Synopsis
 Description
 -----------
 
-``mongoc_gridfs_bucket_t`` provides a MongoDB GridFS implementation, superseding :symbol:`mongoc_gridfs_t`. See the `GridFS MongoDB documentation <https://docs.mongodb.com/manual/core/gridfs/>`_.
+``mongoc_gridfs_bucket_t`` provides a spec-compliant MongoDB GridFS implementation, superseding :symbol:`mongoc_gridfs_t`. See the `GridFS MongoDB documentation <https://docs.mongodb.com/manual/core/gridfs/>`_.
 
 Thread Safety
 -------------
 
-``mongoc_gridfs_bucket_t`` is NOT thread-safe and should only be used in the same thread as the owning :symbol:`mongoc_client_t`.
+:symbol:`mongoc_gridfs_bucket_t` is NOT thread-safe and should only be used in the same thread as the owning :symbol:`mongoc_client_t`.
+
+Lifecycle
+---------
+
+It is an error to free a :symbol:`mongoc_gridfs_bucket_t` before freeing all derived instances of :symbol:`mongoc_stream_t`. The owning :symbol:`mongoc_client_t` must outlive the :symbol:`mongoc_gridfs_bucket_t`.
+
 
 Example
 -------
@@ -29,6 +35,11 @@ Example
    :language: c
    :caption: example-gridfs-bucket.c
 
+See also
+--------
+
+- The `MongoDB GridFS specification <https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst>`_.
+- The non spec-compliant :symbol:`mongoc_gridfs_t`.
 
 .. only:: html
 

src/libmongoc/doc/mongoc_gridfs_t.rst

@@ -3,6 +3,10 @@
 mongoc_gridfs_t
 ===============
 
+.. warning::
+
+  This GridFS implementation does not conform to the `MongoDB GridFS specification <https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst>`_. For a spec compliant implementation, use :symbol:`mongoc_gridfs_bucket_t`.
+
 Synopsis
 --------
 
@@ -42,6 +46,12 @@ Example
    :language: c
    :caption: example-gridfs.c
 
+See also
+--------
+
+- The `MongoDB GridFS specification <https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst>`_.
+- The spec-compliant :symbol:`mongoc_gridfs_bucket_t`.
+
 .. only:: html
 
   Functions