[CDRIVER-3441] Document mongoc_handshake_data_append Created: 02/Dec/19  Updated: 13/Sep/21  Resolved: 13/Sep/21

Status: Closed
Project: C Driver
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major - P3
Reporter: Rathi Gnanasekaran Assignee: Jesse Williamson (Inactive)
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by CXX-1881 Add client metadata support for wrapp... Closed
Related
related to CDRIVER-4142 Use separate handshake metadata for c... Backlog
is related to CDRIVER-3434 Add client metadata support for wrapp... Closed

 Comments   
Comment by Githook User [ 13/Sep/21 ]

Author:

{'name': 'Jesse Williamson', 'email': 'jesse.williamson@mongodb.com', 'username': 'chardan'}

Message: Fix CDRIVER3441 - document mongoc_handshake_data_append and alias as … (#852)

  • Fix CDRIVER3441 - document mongoc_handshake_data_append and alias as mongoc_add_driver_info

I took a slightly different tack on this and made the older form an alias to the preferred,
newer one.

https://jira.mongodb.org/browse/CDRIVER-3441

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>

  • Add Sphinx documentation.

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>

  • Move inline documentation out of source.

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>

  • Add test showing that forwarding function can be called.

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>

  • Revert renaming and forwarding function.

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>

  • Update documentation: this is not deprecated, we will be offering an
    alternative.

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>

  • Add mongoc_handshake_data_append into the TOC/document structure.

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>

  • Update mongoc_handshake_data_append documentation to more accurately describe
    server monitoring and initiation. Some cosmetic adjustments.

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>

  • Update example responses to reflect current behavior.

Signed-off-by: Jesse Williamson <jesse.williamson@mongodb.com>
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/4835c38aafa6d8954321f93f49a6458756e66053

Comment by Kevin Albertson [ 08/Sep/21 ]

Given the likliehood that CDRIVER-4142 will introduce a new preferred way of setting handshake metadata at a client level, I am in favor of proceeding with only documenting the existing mongoc_handshake_data_append and not introducing a new alias.

Comment by Jesse Williamson (Inactive) [ 30/Aug/21 ]

https://github.com/mongodb/mongo-c-driver/pull/852

Comment by Jesse Williamson (Inactive) [ 24/Aug/21 ]

On a related (but not entirely germane) note: have we considered a publicly available maintainence interface?

int mongoc_reserved_maint(void *in_ctx, void *out_ctx);

...which is publicly available and documented, but reserved for internal use rather than for user calls. In practice,
this could take a struct with data and function pointers, and optionally return values.

Comment by Jesse Williamson (Inactive) [ 24/Aug/21 ]

Since this is "public but undocumented", should we also /consider/ renaming the function (which would potentially break external code, but not put us in the position of maintaining undocumented aliases)? I can see this both ways: people definitely don't like having their program suddenly fail to link, but also aliases
of things intentionally undocumented... feels extremely itchy.

Note: seeing that this has been around since 2016, I'm inclined to say we shouldn't break it. But as this will be our "last chance" to do so, it's probably still worth talking about.

Generated at Wed Feb 07 21:18:03 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.