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