<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Wed Feb 07 21:08:55 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary append 'field=key&field=summary' to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>MongoDB Jira</title>
    <link>https://jira.mongodb.org</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>9.7.1</version>
        <build-number>970001</build-number>
        <build-date>13-04-2023</build-date>
    </build-info>


<item>
            <title>[CDRIVER-254] Generate API documentation for libmongc and libbson</title>
                <link>https://jira.mongodb.org/browse/CDRIVER-254</link>
                <project id="10030" key="CDRIVER">C Driver</project>
                    <description>&lt;p&gt;We need to cleanup the in-code documentation to use the same format everywhere.&lt;/p&gt;

&lt;p&gt;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).&lt;/p&gt;

&lt;p&gt;We can then add gtk-doc support to autogen.sh/configure.ac/etc.&lt;/p&gt;

&lt;p&gt;You can see a small example here: &lt;a href=&quot;http://hergert.me/docs/libbson/bson-BSON-Documents.html&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;http://hergert.me/docs/libbson/bson-BSON-Documents.html&lt;/a&gt;&lt;/p&gt;</description>
                <environment></environment>
        <key id="98068">CDRIVER-254</key>
            <summary>Generate API documentation for libmongc and libbson</summary>
                <type id="3" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14718&amp;avatarType=issuetype">Task</type>
                                            <priority id="4" iconUrl="https://jira.mongodb.org/images/icons/priorities/minor.svg">Minor - P4</priority>
                        <status id="6" iconUrl="https://jira.mongodb.org/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="success"/>
                                    <resolution id="9">Done</resolution>
                                        <assignee username="christian.hergert@10gen.com">Christian Hergert</assignee>
                                    <reporter username="christian.hergert@10gen.com">Christian Hergert</reporter>
                        <labels>
                    </labels>
                <created>Mon, 11 Nov 2013 22:07:11 +0000</created>
                <updated>Thu, 19 Jun 2014 10:12:04 +0000</updated>
                            <resolved>Thu, 5 Dec 2013 02:00:38 +0000</resolved>
                                                    <fixVersion>0.90.0</fixVersion>
                                                        <votes>0</votes>
                                    <watches>3</watches>
                                                                                                                <comments>
                            <comment id="627282" author="gianfranco" created="Thu, 19 Jun 2014 10:12:04 +0000"  >&lt;p&gt;Great.&lt;br/&gt;
Should we reopen this ticket or if we create a new one, should it be in CDRIVER or DOCS?&lt;/p&gt;</comment>
                            <comment id="625055" author="christian.hergert@10gen.com" created="Tue, 17 Jun 2014 19:48:03 +0000"  >&lt;p&gt;It looks like we only have the &lt;a href=&quot;http://api.mongodb.org/c/0.96.2/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;http://api.mongodb.org/c/0.96.2/&lt;/a&gt; main driver docs up. We need to upload the libbson docs as well.&lt;/p&gt;

&lt;p&gt;But for the record, the docs can also be found in the libbson tarball under docs/html/&lt;/p&gt;</comment>
                            <comment id="624278" author="gianfranco" created="Tue, 17 Jun 2014 11:25:15 +0000"  >&lt;p&gt;Where are the docs?&lt;br/&gt;
The only url i could found googling for &quot;A Cross Platform BSON Library for C&quot; was:&lt;br/&gt;
&lt;a href=&quot;http://hergert.me/docs/libbson/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;http://hergert.me/docs/libbson/&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;I believe they should be in &lt;a href=&quot;http://api.mongodb.org/libbson/&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;http://api.mongodb.org/libbson/&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Maybe we need DOCS ticket?&lt;/p&gt;</comment>
                            <comment id="465964" author="christian.hergert@10gen.com" created="Thu, 5 Dec 2013 02:00:38 +0000"  >&lt;p&gt;Fixed and released in 0.90.0.&lt;/p&gt;</comment>
                            <comment id="462845" author="jason.carey" created="Wed, 27 Nov 2013 20:33:39 +0000"  >&lt;p&gt;I&apos;m done with the main libmongoc documentation.  Passing it your way for the libbson stuff&lt;/p&gt;</comment>
                            <comment id="459300" author="jason.carey" created="Wed, 20 Nov 2013 20:06:18 +0000"  >&lt;p&gt;Sounds good.  It may make sense to leave some of the comments in .c files, where it&apos;s about the implementation (not the interface).  I&apos;ll clean up the duplicative stuff as I notice it.&lt;/p&gt;</comment>
                            <comment id="459291" author="christian.hergert@10gen.com" created="Wed, 20 Nov 2013 19:57:50 +0000"  >&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;Additionally, I&apos;d like to remove the in code documentation, because the only thing worse than not having docs, is having multiple docs that aren&apos;t the same.&lt;/p&gt;</comment>
                            <comment id="459198" author="jason.carey" created="Wed, 20 Nov 2013 18:28:32 +0000"  >&lt;p&gt;It&apos;s certainly possible.  I&apos;ve found a few code extractors sniffing around and we could make it happen with some conventions.&lt;/p&gt;

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

&lt;p&gt;I&apos;ve got a couple of thoughts:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;We&apos;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&apos;t want to change semantics without breaking ABI, so once written and published our docs are probably pretty much frozen.&lt;/li&gt;
	&lt;li&gt;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&apos;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&apos;m programming to that api as a user.&lt;/li&gt;
	&lt;li&gt;I&apos;m really liking the ability to mix function level documentation (3) with high level docs (7).  Things just flow naturally, and I don&apos;t feel like I&apos;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.&lt;/li&gt;
&lt;/ul&gt;


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

&lt;p&gt;Alternatively, we can fall back to doxygen, or I can give gtk-doc another shot.  I&apos;m just not super happy with the flexibility those offer.  I&apos;d like something specialized for writing documentation, not something focused on extracting comments from code.&lt;/p&gt;</comment>
                            <comment id="459128" author="christian.hergert@10gen.com" created="Wed, 20 Nov 2013 17:24:19 +0000"  >&lt;p&gt;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.&lt;/p&gt;</comment>
                            <comment id="459085" author="jason.carey" created="Wed, 20 Nov 2013 16:28:47 +0000"  >&lt;p&gt;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.&lt;/p&gt;</comment>
                    </comments>
                    <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_15850" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummary">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            <customfield id="customfield_12550" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>2|hrmmmf:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10558" key="com.pyxis.greenhopper.jira:gh-global-rank">
                        <customfieldname>Rank (Obsolete)</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>45743</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                    <customfield id="customfield_10557" key="com.pyxis.greenhopper.jira:gh-sprint">
                        <customfieldname>Sprint</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue id="60">Sprint 1</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            </customfields>
    </item>
</channel>
</rss>