[CDRIVER-1689] Document mongoc_handshake_data_append in the .h, not public doc Created: 11/Oct/16  Updated: 19/Oct/16  Resolved: 11/Oct/16

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

Type: Bug Priority: Major - P3
Reporter: David Golden Assignee: Hannes Magnusson
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to CDRIVER-1470 Lingering manpages without a home Closed
is related to CDRIVER-1391 Add docs for providing MongoDB Handsh... Closed

 Description   

Despite the existence of a page on mongoc_handshake_data_append, no other pages appear to link to it.



 Comments   
Comment by Githook User [ 11/Oct/16 ]

Author:

{u'username': u'bjori', u'name': u'Hannes Magnusson', u'email': u'bjori@php.net'}

Message: CDRIVER-1689 Document mongoc_handshake_data_append in the .h, not public doc
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/2d085cf9ca8180a08cfcd8dd05909ab05bf0b430

Comment by David Golden [ 11/Oct/16 ]

Removing the doc page and adding docs to the header would be fine.

Comment by Hannes Magnusson [ 11/Oct/16 ]

I don't mind removing the doc page. In our emails regarding this feature to the C++, PHP and HHVM driver developer we linked this page specifically, since it was only made for you guys. If you have no use for it, it makes no sense for us to keep it. I don't agree that this private internal function should be mentioned in the initialization section. Telling people about cool feature they are not supposed to use, will make them use it.

There should be no other "hidden" pages. See CDRIVER-1470 which fixed those that I found couple of months ago.

Regarding searchability of our docs and improving our doc system, this was part of our OKRs for this quarter, but got reduce to not find a fully now system but improving the hosting situation so they get at least published.

Our docs live on http://mongoc.org/ and are updated on each release.
Bleeding edge, in development, docs are available on https://s3.amazonaws.com/mciuploads/mongo-c-driver/docs/latest/index.html and are regenerated per commit.
Similarly, libbson docs are also available on http://mongoc.org/ and per commit docs available on https://s3.amazonaws.com/mciuploads/libbson/docs/latest/index.html

If you have general suggestions regarding the docs, lets open another ticket for that, not a fan of mixing so many things into a ticket about mongoc_handshake_data_append().

If I remove the doc page and add docblock in the header file, like you suggested, would that resolve this ticket?

Comment by David Golden [ 11/Oct/16 ]

If you really don't want it part of the public docs, maybe remove the page and put its content in a comment in the header file that declares it.

FWIW, as a developer of a driver based on mongoc, I find it annoying to have to hunt for documentation of a public API function, particularly since the docs site isn't easily searchable (until indexed by Google). Are there any other public function that are undocumented or have hidden docs?

Personally, I suggest at least mentioning it in the initialization section with a single sentence statement along the lines of "for developers of drivers built on libmongoc only; see code comments for usage". Otherwise, how is a third party driver dev supposed to know to use it?

Comment by Hannes Magnusson [ 11/Oct/16 ]

It was intentional. If we had a jailbreaking api, it would be for this function. Its not a function that normal apps should use, only drivers based on mongoc. It is also not part of any toc, for the same reason.

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