[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: |
|
||||||||||||
| 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: |
| 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 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. 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. |