<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Wed Feb 07 21:14:10 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-2095] Document what false means as return value</title>
                <link>https://jira.mongodb.org/browse/CDRIVER-2095</link>
                <project id="10030" key="CDRIVER">C Driver</project>
                    <description>&lt;p&gt;The documentations never state what a &lt;tt&gt;false&lt;/tt&gt; return value means. Does it mean a NULL was passed? Internal error, such as allocation errors? What sort of scenarios lead to a return value being false rather then &lt;tt&gt;true&lt;/tt&gt;?&lt;br/&gt;
This needs to documented in one location and linked from functions with boolean return values&lt;/p&gt;

&lt;p&gt;Following is the original report&lt;br/&gt;
&amp;#8212;&lt;/p&gt;

&lt;p&gt;The setters on &lt;tt&gt;mongoc_find_and_modify_opts_t&lt;/tt&gt; like &lt;tt&gt;mongoc_find_and_modify_opts_set_sort&lt;/tt&gt; and others generally return a bool and are documented as &quot;Returns true if it successfully added the option to the builder.&quot;&lt;/p&gt;

&lt;p&gt;There is no documentation of what &quot;false&quot; means.  Looking at the code, some of them appear to have no way to return false.  Others return false if their input is null.  Without inspecting the code, we have no way of knowing if we should be checking the return value and without documentation, the behavior is unspecified and thus subject to change.&lt;/p&gt;

&lt;p&gt;We are auditing all mongocxx calls to libmongoc to ensure mongocxx handles error conditions according to the libmongoc documentation.  We can&apos;t do that if return value documentation isn&apos;t complete.&lt;/p&gt;

&lt;p&gt;For all the setters, we would like the following changes to documentation:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;document what &apos;false&apos; means OR document that the function only ever returns true&lt;/li&gt;
&lt;/ul&gt;
</description>
                <environment></environment>
        <key id="367187">CDRIVER-2095</key>
            <summary>Document what false means as return value</summary>
                <type id="4" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14710&amp;avatarType=issuetype">Improvement</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="jesse@mongodb.com">A. Jesse Jiryu Davis</assignee>
                                    <reporter username="david.golden@mongodb.com">David Golden</reporter>
                        <labels>
                            <label>neweng</label>
                    </labels>
                <created>Thu, 23 Mar 2017 02:08:51 +0000</created>
                <updated>Mon, 7 May 2018 19:51:16 +0000</updated>
                            <resolved>Fri, 5 May 2017 18:46:02 +0000</resolved>
                                                    <fixVersion>1.7.0</fixVersion>
                                    <component>libmongoc</component>
                                        <votes>0</votes>
                                    <watches>3</watches>
                                                                                                                <comments>
                            <comment id="1565973" author="xgen-internal-githook" created="Fri, 5 May 2017 19:29:53 +0000"  >&lt;p&gt;Author:&lt;/p&gt;
{u&apos;username&apos;: u&apos;ajdavis&apos;, u&apos;name&apos;: u&apos;A. Jesse Jiryu Davis&apos;, u&apos;email&apos;: u&apos;jesse@mongodb.com&apos;}
&lt;p&gt;Message: &lt;a href=&quot;https://jira.mongodb.org/browse/CDRIVER-2095&quot; title=&quot;Document what false means as return value&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CDRIVER-2095&quot;&gt;&lt;del&gt;CDRIVER-2095&lt;/del&gt;&lt;/a&gt; allow NULL findandmodify options&lt;br/&gt;
Branch: master&lt;br/&gt;
&lt;a href=&quot;https://github.com/mongodb/mongo-c-driver/commit/82dbe605e91fb817fb56fa1954e3bf97a3a28b09&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://github.com/mongodb/mongo-c-driver/commit/82dbe605e91fb817fb56fa1954e3bf97a3a28b09&lt;/a&gt;&lt;/p&gt;</comment>
                            <comment id="1565155" author="xgen-internal-githook" created="Fri, 5 May 2017 02:39:29 +0000"  >&lt;p&gt;Author:&lt;/p&gt;
{u&apos;username&apos;: u&apos;ajdavis&apos;, u&apos;name&apos;: u&apos;A. Jesse Jiryu Davis&apos;, u&apos;email&apos;: u&apos;jesse@mongodb.com&apos;}
&lt;p&gt;Message: &lt;a href=&quot;https://jira.mongodb.org/browse/CDRIVER-2095&quot; title=&quot;Document what false means as return value&quot; class=&quot;issue-link&quot; data-issue-key=&quot;CDRIVER-2095&quot;&gt;&lt;del&gt;CDRIVER-2095&lt;/del&gt;&lt;/a&gt; improve error-reporting docs&lt;br/&gt;
Branch: master&lt;br/&gt;
&lt;a href=&quot;https://github.com/mongodb/mongo-c-driver/commit/62e8fc399e9a3f23cca6493bf57d728d4d7bbf77&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://github.com/mongodb/mongo-c-driver/commit/62e8fc399e9a3f23cca6493bf57d728d4d7bbf77&lt;/a&gt;&lt;/p&gt;</comment>
                            <comment id="1553954" author="david.golden" created="Thu, 20 Apr 2017 18:25:51 +0000"  >&lt;p&gt;I think you misunderstand.&lt;/p&gt;

&lt;p&gt;Right now, we don&apos;t know &amp;#8211; without code inspection &amp;#8211; whether failure means &quot;something went wrong in libmongoc&quot; (e.g. memory allocation error) or &quot;the input was invalid&quot; or both or neither.  We&apos;d like that documented so that we know what contract libmongoc is offering and thus we know what kind of error handling to invoke.  E.g. abort() vs throw an &quot;invalid parameter&quot; exception.&lt;/p&gt;</comment>
                            <comment id="1553877" author="bjori" created="Thu, 20 Apr 2017 17:12:06 +0000"  >&lt;p&gt;The functions state they return true on success, and therefore false on failure.&lt;/p&gt;

&lt;p&gt;Today, there may be couple of functions that cannot fail and therefore don&apos;t return false, but updating the documentation to say &quot;will never return false&quot; is not going to happen as it is totally incorrect.&lt;/p&gt;

&lt;p&gt;The exact handling today is an implementation detail.&lt;br/&gt;
Declaring the function as void will be equally bad, as when the day comes where something might fail, we can&apos;t change the prototype and we&apos;ve shot ourself in the foot.&lt;/p&gt;

&lt;p&gt;As it is now, the function is both future proof, and the documentations are correct. The return value should be checked.&lt;/p&gt;</comment>
                    </comments>
                <issuelinks>
                            <issuelinktype id="10011">
                    <name>Depends</name>
                                                                <inwardlinks description="is depended on by">
                                        <issuelink>
            <issuekey id="320711">CXX-1066</issuekey>
        </issuelink>
                            </inwardlinks>
                                    </issuelinktype>
                    </issuelinks>
                <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|hsx33z:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10558" key="com.pyxis.greenhopper.jira:gh-global-rank">
                        <customfieldname>Rank (Obsolete)</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>9223372036854775807</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            </customfields>
    </item>
</channel>
</rss>