[CDRIVER-254] Generate API documentation for libmongc and libbson Created: 11/Nov/13  Updated: 19/Jun/14  Resolved: 05/Dec/13

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

Type: Task Priority: Minor - P4
Reporter: Christian Hergert Assignee: Christian Hergert
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

We need to cleanup the in-code documentation to use the same format everywhere.

I think we are going to go with the gtk-doc format since it can win us gobject-introspection (for dynamic language support for free).

We can then add gtk-doc support to autogen.sh/configure.ac/etc.

You can see a small example here: http://hergert.me/docs/libbson/bson-BSON-Documents.html



 Comments   
Comment by Gianfranco Palumbo [ 19/Jun/14 ]

Great.
Should we reopen this ticket or if we create a new one, should it be in CDRIVER or DOCS?

Comment by Christian Hergert [ 17/Jun/14 ]

It looks like we only have the http://api.mongodb.org/c/0.96.2/ main driver docs up. We need to upload the libbson docs as well.

But for the record, the docs can also be found in the libbson tarball under docs/html/

Comment by Gianfranco Palumbo [ 17/Jun/14 ]

Where are the docs?
The only url i could found googling for "A Cross Platform BSON Library for C" was:
http://hergert.me/docs/libbson/

I believe they should be in http://api.mongodb.org/libbson/

Maybe we need DOCS ticket?

Comment by Christian Hergert [ 05/Dec/13 ]

Fixed and released in 0.90.0.

Comment by Mira Carey [ 27/Nov/13 ]

I'm done with the main libmongoc documentation. Passing it your way for the libbson stuff

Comment by Mira Carey [ 20/Nov/13 ]

Sounds good. It may make sense to leave some of the comments in .c files, where it's about the implementation (not the interface). I'll clean up the duplicative stuff as I notice it.

Comment by Christian Hergert [ 20/Nov/13 ]

I think it is acceptable to maintain them out of the source code if we make it our policy to update them upon adding symbols.

Additionally, I'd like to remove the in code documentation, because the only thing worse than not having docs, is having multiple docs that aren't the same.

Comment by Mira Carey [ 20/Nov/13 ]

It's certainly possible. I've found a few code extractors sniffing around and we could make it happen with some conventions.

If we really want to go that way, I'm not sure asciidoc is the right choice as it doesn't do actual code analysis like doxygen or gtk-doc. We'd just be extracting bits of the header, literally.

I've got a couple of thoughts:

  • We're planning on specifying an ABI and then changing it only very infrequently. Which means our user documentation will change only very infrequently. On top of that, we probably don't want to change semantics without breaking ABI, so once written and published our docs are probably pretty much frozen.
  • You often want pretty different documentation for function definitions and prototypes (prototypes have usage info, implementation has an explanation of how things are supposed to be working). Which leads to maintaining a version in the headers and a version for the .c files. Given that we'll be maintaining two copies anyway, I usually prefer man pages over any markup that sits comfortably above a function prototype. At least when I'm programming to that api as a user.
  • I'm really liking the ability to mix function level documentation (3) with high level docs (7). Things just flow naturally, and I don't feel like I'm making the source unreadable if I put in more detail. As an example, mongoc_uri needs to talk about the connection string format and mongoc-uri.h is a terrible place to document that.

Honestly, if we want idiomatic man pages, rather than super sterile generated ones, our best bet would probably be doxygen w/ sphinx. There's a plugin for pulling doxygen comments and definitions into sphinx, which would give us the best of both worlds.

Alternatively, we can fall back to doxygen, or I can give gtk-doc another shot. I'm just not super happy with the flexibility those offer. I'd like something specialized for writing documentation, not something focused on extracting comments from code.

Comment by Christian Hergert [ 20/Nov/13 ]

Is there any way that we can have the documentation in the code with ascii doc? I would really prefer to have it above each function so it gets updated when changing an implementation.

Comment by Mira Carey [ 20/Nov/13 ]

We opted for asciidoc (over gtkdoc or doxygen) under the assumption that man page style docs are going to appeal more idiomatically to the C community than the kind of thing doxygen or gtk-doc usually output.

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