<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Thu Feb 08 08:34:30 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>[GODRIVER-572] TransformDocument should document how it handles nil</title>
                <link>https://jira.mongodb.org/browse/GODRIVER-572</link>
                <project id="14289" key="GODRIVER">Go Driver</project>
                    <description>&lt;p&gt;nil is equivalent to an empty document, but this is not documented.&lt;/p&gt;</description>
                <environment></environment>
        <key id="606790">GODRIVER-572</key>
            <summary>TransformDocument should document how it handles nil</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="13201">Fixed</resolution>
                                        <assignee username="isabella.siu@mongodb.com">Isabella Siu</assignee>
                                    <reporter username="david.golden@mongodb.com">David Golden</reporter>
                        <labels>
                    </labels>
                <created>Tue, 18 Sep 2018 20:46:29 +0000</created>
                <updated>Sat, 28 Oct 2023 11:39:26 +0000</updated>
                            <resolved>Thu, 21 Feb 2019 18:22:20 +0000</resolved>
                                                    <fixVersion>1.0.0-rc1</fixVersion>
                                    <component>Documentation</component>
                                        <votes>0</votes>
                                    <watches>3</watches>
                                                                                                                <comments>
                            <comment id="2158695" author="xgen-internal-githook" created="Thu, 21 Feb 2019 18:20:50 +0000"  >&lt;p&gt;Author:&lt;/p&gt;
{&apos;name&apos;: &apos;Isabella Siu&apos;, &apos;email&apos;: &apos;isabella.siu@10gen.com&apos;, &apos;username&apos;: &apos;iwysiu&apos;}
&lt;p&gt;Message: &lt;a href=&quot;https://jira.mongodb.org/browse/GODRIVER-572&quot; title=&quot;TransformDocument should document how it handles nil&quot; class=&quot;issue-link&quot; data-issue-key=&quot;GODRIVER-572&quot;&gt;&lt;del&gt;GODRIVER-572&lt;/del&gt;&lt;/a&gt; document that Client, Collection, and Database methods will return an ErrNilDocument if nil is passed in for an interface{}&lt;/p&gt;

&lt;p&gt;Change-Id: I1dd743891dd2ca49ebee0b76fa15f5ea738813a4&lt;br/&gt;
Branch: master&lt;br/&gt;
&lt;a href=&quot;https://github.com/mongodb/mongo-go-driver/commit/f085d9c2b7466c04f3fd356fe1174c5f614e1632&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://github.com/mongodb/mongo-go-driver/commit/f085d9c2b7466c04f3fd356fe1174c5f614e1632&lt;/a&gt;&lt;/p&gt;</comment>
                            <comment id="2157521" author="isabella.siu" created="Wed, 20 Feb 2019 20:02:58 +0000"  >&lt;p&gt;code review:&#160;&lt;a href=&quot;https://review.gerrithub.io/c/mongodb/mongo-go-driver/+/445618&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;https://review.gerrithub.io/c/mongodb/mongo-go-driver/+/445618&lt;/a&gt;&lt;/p&gt;</comment>
                            <comment id="2107845" author="david.golden" created="Mon, 7 Jan 2019 21:05:25 +0000"  >&lt;p&gt;I don&apos;t think that&apos;s enough.  Empty interface is like &lt;tt&gt;void*&lt;/tt&gt;.  Just saying &quot;non-nil&quot; isn&apos;t enough.  We should be positively listing what types/interfaces are allowed.&lt;/p&gt;

&lt;p&gt;(Doing it in doc.go seems fine, though.)&lt;/p&gt;</comment>
                            <comment id="2107825" author="divjot.arora" created="Mon, 7 Jan 2019 20:58:14 +0000"  >&lt;p&gt;I think adding it to &lt;tt&gt;doc.go&lt;/tt&gt; is good enough. Just a small note like &quot;all methods in collection.go that take params of type interface{} will return ErrNilDocument if nil is passed in&quot;&lt;/p&gt;</comment>
                            <comment id="2107823" author="david.golden" created="Mon, 7 Jan 2019 20:58:07 +0000"  >&lt;p&gt;As far as I can see, there is zero documentation in the mongo package about what types are acceptable to the empty interface parameters that are intended to take &quot;documents&quot;.&lt;/p&gt;

&lt;p&gt;I think now that &lt;tt&gt;TransformDocument&lt;/tt&gt; is private, there still needs to be such documentation somewhere.  (See for example, this &lt;a href=&quot;https://metacpan.org/pod/MongoDB::Collection#Terminology&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;terminology&lt;/a&gt; section in Perl driver documentation).  So perhaps this just needs to be renamed to &quot;Document what types are allowed as documents for empty interface parameters&quot;.&lt;/p&gt;</comment>
                            <comment id="2107816" author="kris.brandow" created="Mon, 7 Jan 2019 20:55:23 +0000"  >&lt;p&gt;We have &lt;tt&gt;ErrNilDocument&lt;/tt&gt;, but if that&apos;s not enough we can call it out in the main documentation in the &lt;tt&gt;doc.go&lt;/tt&gt; file. I don&apos;t think we should add it to every single CRUD method.&lt;/p&gt;</comment>
                            <comment id="2107811" author="divjot.arora" created="Mon, 7 Jan 2019 20:52:42 +0000"  >&lt;p&gt;yep - not sure if we should make a new ticket for the docs or just modify this ticket to add documentation for all CRUD functions to say when nil is and isn&apos;t allowed.&lt;/p&gt;</comment>
                            <comment id="2107806" author="kris.brandow" created="Mon, 7 Jan 2019 20:51:05 +0000"  >&lt;p&gt;It&apos;s &lt;tt&gt;transformDocument&lt;/tt&gt; itself that returns an error if you provide it with &lt;tt&gt;nil&lt;/tt&gt;, so it&apos;ll return an error for inserts and finds alike.&lt;/p&gt;</comment>
                            <comment id="2107803" author="divjot.arora" created="Mon, 7 Jan 2019 20:48:23 +0000"  >&lt;p&gt;&lt;del&gt;Things like the filter for Find(), however, still pass through transformDocument() without being checked for nil.&lt;/del&gt;&lt;/p&gt;

&lt;p&gt;Previous comment was incorrect. transformDocument() now checks to see if the value passed in is nil and returns an error if it is. This behavior isn&apos;t document anywhere, though. At the very least, the documentation for Find() should say that a nil filter isn&apos;t allowed.&lt;/p&gt;</comment>
                            <comment id="2107795" author="kris.brandow" created="Mon, 7 Jan 2019 20:45:06 +0000"  >&lt;p&gt;Since&#160;&lt;a href=&quot;https://jira.mongodb.org/browse/GODRIVER-659&quot; title=&quot;Collection allows insertion of a nil value&quot; class=&quot;issue-link&quot; data-issue-key=&quot;GODRIVER-659&quot;&gt;&lt;del&gt;GODRIVER-659&lt;/del&gt;&lt;/a&gt; we no longer allow &lt;tt&gt;nil&lt;/tt&gt; as a valid parameter for anything that goes through &lt;tt&gt;transformDocument&lt;/tt&gt;. Given that, do we still need to document this?&lt;/p&gt;</comment>
                            <comment id="2029912" author="david.golden" created="Thu, 11 Oct 2018 10:47:51 +0000"  >&lt;p&gt;It&apos;s possible there needs to be a top-level documentation section on how empty interface documents are handled across the API (assuming that behavior is universal).&lt;/p&gt;</comment>
                            <comment id="2029750" author="divjot.arora" created="Thu, 11 Oct 2018 02:44:35 +0000"  >&lt;p&gt;From what I understand, the TransformDocument function previously used by collection.go has been replaced by a transformDocument function defined in mongo/mongo.go. The documentation for the collection.go functions should be updated to reflect this because many of them say &quot;See TransformDocument for the list of valid types for documents.&quot;&lt;/p&gt;

&lt;p&gt;I&apos;m not sure how docs for private functions work. Should transformDocument be documented for users or should each collection.go function that uses it specify the types that can be passed to it?&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_10857" key="com.pyxis.greenhopper.jira:gh-epic-link">
                        <customfieldname>Epic Link</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>GODRIVER-530</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_12550" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>2|huduvz:</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>