From 5613eb6c5386cba70d0838f924a5764e6cc00be6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 11:52:54 -0500 Subject: [PATCH 1/5] DOCSP-45356: i&h + code doc --- snooty.toml | 1 + source/code-documentation.txt | 352 +++++++++++++++++ source/contributing.txt | 21 -- source/contributing/code-documentation.txt | 353 ------------------ .../contributing/contributing-guidelines.txt | 43 --- source/index.txt | 6 +- source/issues-and-help.txt | 85 +++++ 7 files changed, 440 insertions(+), 421 deletions(-) create mode 100644 source/code-documentation.txt delete mode 100644 source/contributing.txt delete mode 100644 source/contributing/code-documentation.txt delete mode 100644 source/contributing/contributing-guidelines.txt create mode 100644 source/issues-and-help.txt diff --git a/snooty.toml b/snooty.toml index 22980ad3..b9bbb429 100644 --- a/snooty.toml +++ b/snooty.toml @@ -13,6 +13,7 @@ toc_landing_pages = [ "/interact-data/specify-query", "/data-modeling", "/configuration", + "/issues-and-help" ] [constants] diff --git a/source/code-documentation.txt b/source/code-documentation.txt new file mode 100644 index 00000000..59d692bc --- /dev/null +++ b/source/code-documentation.txt @@ -0,0 +1,352 @@ +.. _mongoid-code-documentation: + +================== +Code Documentation +================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about {+odm+}'s code documentation +conventions. If you have a suggestion to improve the API documentation +or introduce a new feature, you can use this guide to help you format +your documentation. + +{+odm+} uses a variation of :github:`YARD `, a {+language+} +documentation tool, for its code documentation. + +.. _mongoid-code-documentation-structure: + +Structure +--------- + +- **Modules:** All class and module definitions should be preceded by + a documentation comment. + + .. code-block:: ruby + + # This is the documentation for the class. It's amazing + # what they do with corrugated cardboard these days. + class CardboardBox + +- **Methods:** All method definitions should be preceded by a + documentation comment. Use ``@param``, ``@yield``, and ``@return`` to + specify inputs and output. To learn more, see the + :ref:`mongoid-code-documentation-type-declaration` section. + + .. code-block:: ruby + + # Turn a person into whatever they'd like to be. + # + # @param [ Person ] person The human to transmogrify. + # + # @return [ Tiger ] The transmogrified result. + def transmogrify(person) + +- **Errors:** Use ``@raise`` to describe errors specific to the method. + + .. code-block:: ruby + + # @raise [ Errors::Validations ] If validation failed. + def validate! + +- **Private Methods:** Private methods must be documented unless they are + so brief and straightforward that it is obvious what they do. Note that, + for example, a method might be brief and straightforward but the type of + its parameter may not be obvious, in which case the parameter must be + appropriately documented. + + .. code-block:: ruby + + private + + # Documentation is optional here. + def do_something_obvious + +- **API Private:** Classes and public methods which are not intended for + external usage should be marked ``@api private``. This macro does not + require a comment. + + Note that, because {+odm+}'s modules are mixed into application classes, + ``private`` visibility of a method does not necessarily indicate its + status as an API private method. + + .. code-block:: ruby + + # This is an internal-only method. + # + # @api private + def dont_call_me_from_outside + +- **Notes and TODOs:** Use ``@note`` to explain caveats, edge cases, + and behavior which may surprise users. Use ``@todo`` to record + follow-ups and suggestions for future improvement. + + .. code-block:: ruby + + # Clear all stored data. + # + # @note This operation deletes data in the database. + # @todo Refactor this method for performance. + def erase_data! + +- **Deprecation:** Use the ``@deprecated`` macro to indicate deprecated + functionality. This macro does not require a comment. + + .. code-block:: ruby + + # This is how we did things back in the day. + # + # @deprecated + def the_old_way + +.. _mongoid-code-documentation-formatting: + +Formatting +---------- + +- **Line Wrapping:** Use double-space indent when wrapping lines of macros. + Do not indent line wraps in the description. + + .. code-block:: ruby + + # This is the description of the method. Line wraps in the description + # should not be indented. + # + # @return [ Symbol ] For macros, wraps must be double-space indented + # on the second, third, etc. lines. + +- **Whitespace:** Do not use leading/trailing empty comment lines, + or more than one consecutive empty comment line. + + .. code-block:: ruby + + # GOOD: + # @return [ Symbol ] The return value + def my_method + + # BAD: + # @return [ Symbol ] The return value + # + def my_method + + # BAD: + # @param [ Symbol ] foo The input value + # + # + # @return [ Symbol ] The return value + def my_method(foo) + +.. _mongoid-code-documentation-type-declaration: + +Type Declaration +---------------- + +- **Type Unions:** Use pipe ``|`` to denote a union of allowed types. + + .. code-block:: ruby + + # @param [ Symbol | String ] name Either a Symbol or a String. + +- **Nested Types:** Use angle brackets ``< >`` to denote type nesting. + + .. code-block:: ruby + + # @param [ Array ] array An Array of symbols. + +- **Hash:** Use comma ``,`` to denote the key and value types. + + .. code-block:: ruby + + # @param [ Hash ] hash A Hash whose keys are Symbols, + # and whose values are Integers. + +- **Array:** Use pipe ``|`` to denote a union of allowed types. + + .. code-block:: ruby + + # @param [ Array ] array An Array whose members must + # be either Symbols or Strings. + +- **Array:** Use comma ``,`` to denote the types of each position in a tuple. + + .. code-block:: ruby + + # @return [ Array ] A 3-member Array whose first + # element is a Symbol, and whose second and third elements are Integers. + +- **Array:** Use pipe ``|`` on the top level if the inner types cannot be + mixed within the Array. + + .. code-block:: ruby + + # @param [ Array | Array ] array An Array containing only + # Symbols, or an Array containing only Hashes. The Array may not contain + # a mix of Symbols and Hashes. + +- **Nested Types:** For clarity, use square brackets ``[ ]`` to denote nested unions + when commas are also used. + + .. code-block:: ruby + + # @param [ Hash ] hash A Hash whose keys are Symbols, + # and whose values are boolean values. + +- **Ruby Values:** Specific values may be denoted in the type using Ruby syntax. + + .. code-block:: ruby + + # @param [ :before | :after ] timing One of the Symbol values :before or :after. + +- **True, False, and Nil:** Use ``true``, ``false``, and ``nil`` rather than + ``TrueClass``, ``FalseClass``, and ``NilClass``. Do not use ``Boolean`` as a type + since it does not exist in Ruby. + + .. code-block:: ruby + + # GOOD: + # @param [ true | false | nil ] bool A boolean or nil value. + + # BAD: + # @param [ TrueClass | FalseClass | NilClass ] bool A boolean or nil value. + # @param [ Boolean ] bool A boolean value. + +- **Return Self:** Specify return value ``self`` where a method returns ``self``. + + .. code-block:: ruby + + # @return [ self ] Returns the object itself. + +- **Splat Args:** Use three-dot ellipses ``...`` in the type declaration and + star ``*`` in the parameter name to denote a splat. + + .. code-block:: ruby + + # @param [ String... ] *items The list of items name(s) as Strings. + def buy_groceries(*items) + +- **Splat Args:** Do not use ``Array`` as the type unless each arg is actually an Array. + + .. code-block:: ruby + + # BAD: + # @param [ Array ] *items The list of items name(s) as Strings. + def buy_groceries(*items) + + buy_groceries("Cheese", "Crackers", "Wine") + + # OK: + # @param [ Array... ] *arrays One or more arrays containing name parts. + def set_people_names(*arrays) + + set_people_names(["Harlan", "Sanders"], ["Jane", "K", ""Doe"], ["Jim", "Beam"]) + +- **Splat Args:** Use comma ``,`` to denote positionality in a splat. + + .. code-block:: ruby + + # @param [ Symbol..., Hash ] *args A list of names, followed by a hash + # as the optional last arg. + def say_hello(*args) + +- **Splat Args:** Specify type unions with square brackets ``[ ]``. + + .. code-block:: ruby + + # @param [ [ String | Symbol ]... ] *fields A splat of mixed Symbols and Strings. + +- **Keyword Arguments:** Following YARD conventions, use ``@param`` for keyword + arguments, and specify keyword argument names as symbols. + + .. code-block:: ruby + + # @param [ String ] query The search string + # @param [ Boolean ] :exact_match Whether to do an exact match + # @param [ Integer ] :results_per_page Number of results + def search(query, exact_match: false, results_per_page: 10) + +- **Hash Options:** Define hash key-value options with ``@option`` macro + immediately following the Hash ``@param``. Note ``@option`` parameter names + are symbols. + + .. code-block:: ruby + + # @param opts [ Hash ] The optional hash argument(s). + # @option opts [ String | Array ] :items The items(s) as Strings to include. + # @option opts [ Integer ] :limit An Integer denoting the limit. + def buy_groceries(opts = {}) + +- **Double Splats:** Use double-star ``**`` in the parameter name to denote a + keyword arg splat (double splat). Note that type does not need declared on + the double-splat element, as it is implicitly . Instead, + define value types with ``@option`` macro below. Note ``@option`` parameter + names are symbols. + + .. code-block:: ruby + + # @param **kwargs The optional keyword argument(s). + # @option **kwargs [ String | Array ] :items The items(s) as Strings to include. + # @option **kwargs [ Integer ] :limit An Integer denoting the limit. + def buy_groceries(**kwargs) + +- **Blocks:** Use ``@yield`` to specify when the method yields to a block. + + .. code-block:: ruby + + # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. + # Must take the person, location, and weapon used. Must return true or false. + def whodunit + yield(:mustard, :ballroom, :candlestick) + end + +- **Blocks:** If the method explicitly specifies a block argument, specify the block + argument using ``@param`` preceded by an ampersand ``&``, and also specify ``@yield``. + Note ``@yield`` should be used even when method calls ``block.call`` rather than + ``yield`` internally. + + .. code-block:: ruby + + # @param &block The block. + # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. + # Must take the person, location, and weapon used. Must return true or false. + def whodunit(&block) + yield(:scarlet, :library, :rope) + end + + # @param &block The block. + # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. + # Must take the person, location, and weapon used. Must return true or false. + def whodunit(&block) + block.call(:plum, :kitchen, :pipe) + end + +- **Blocks:** Use ``@yieldparam`` and ``@yieldreturn`` instead of ``@yield`` where + beneficial for clarity. + + .. code-block:: ruby + + # @param &block The block. + # @yieldparam [ Symbol ] The person. + # @yieldparam [ Symbol ] The location. + # @yieldparam [ Symbol ] The weapon used. + # @yieldreturn [ true | false ] Whether the guess is correct. + def whodunit(&block) + yield(:peacock, :conservatory, :wrench) + end + +- **Proc Args:** Proc arguments should use ``@param`` (not ``@yield``). The + inputs to the proc may be specified as subtype(s). + + .. code-block:: ruby + + # @param [ Proc ] my_proc Proc argument which must + # take 3 integers and must return true or false whether the guess is valid. + def guess_three(my_proc) + my_proc.call(42, 7, 88) + end diff --git a/source/contributing.txt b/source/contributing.txt deleted file mode 100644 index abb7d737..00000000 --- a/source/contributing.txt +++ /dev/null @@ -1,21 +0,0 @@ -.. _contributing: - -************ -Contributing -************ - -.. default-domain:: mongodb - -.. toctree:: - :titlesonly: - - contributing/code-documentation - contributing/contributing-guidelines - -Overview --------- - -Learn how to contribute to the Mongoid repository in the following sections: - -- :ref:`Code Documentation ` -- :ref:`Contributing Guidelines ` \ No newline at end of file diff --git a/source/contributing/code-documentation.txt b/source/contributing/code-documentation.txt deleted file mode 100644 index 9713ce27..00000000 --- a/source/contributing/code-documentation.txt +++ /dev/null @@ -1,353 +0,0 @@ -.. _code-documentation: - -****************** -Code Documentation -****************** - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - - -Code Documentation -================== - -Mongoid uses its own flavor of `YARD `_ -for code documentation. Please note the conventions outlined in this document. - - -.. _code-documentation-structure: - -Structure ---------- - -- **Modules:** All class and module definitions should be preceded by - a documentation comment. - - .. code-block:: ruby - - # This is the documentation for the class. It's amazing - # what they do with corrugated cardboard these days. - class CardboardBox - -- **Methods:** All method definitions should be preceded by a documentation comment. - Use ``@param``, ``@yield``, and ``@return`` to specify inputs and output. - For further details, refer to - :ref:`Type Declaration ` below. - - .. code-block:: ruby - - # Turn a person into whatever they'd like to be. - # - # @param [ Person ] person The human to transmogrify. - # - # @return [ Tiger ] The transmogrified result. - def transmogrify(person) - -- **Errors:** Use ``@raise`` to explain errors specific to the method. - - .. code-block:: ruby - - # @raise [ Errors::Validations ] If validation failed. - def validate! - -- **Private Methods:** Private methods should be documented unless they are - so brief and straightforward that it is obvious what they do. Note that, - for example, a method may be brief and straightforward but the type of - its parameter may not be obvious, in which case the parameter must be - appropriately documented. - - .. code-block:: ruby - - private - - # Documentation is optional here. - def do_something_obvious - -- **API Private:** Classes and public methods which are not intended for - external usage should be marked ``@api private``. This macro does not - require a comment. - - Note that, because Mongoid's modules are mixed into application classes, - ``private`` visibility of a method does not necessarily indicate its - status as an API private method. - - .. code-block:: ruby - - # This is an internal-only method. - # - # @api private - def dont_call_me_from_outside - -- **Notes and TODOs:** Use ``@note`` to explain caveats, edge cases, - and behavior which may surprise users. Use ``@todo`` to record - follow-ups and suggestions for future improvement. - - .. code-block:: ruby - - # Clear all stored data. - # - # @note This operation deletes data in the database. - # @todo Refactor this method for performance. - def erase_data! - -- **Deprecation:** Use the ``@deprecated`` macro to indicate deprecated - functionality. This macro does not require a comment. - - .. code-block:: ruby - - # This is how we did things back in the day. - # - # @deprecated - def the_old_way - - -.. _code-documentation-formatting: - -Formatting ----------- - -- **Line Wrapping:** Use double-space indent when wrapping lines of macros. - Do not indent line wraps in the description. - - .. code-block:: ruby - - # This is the description of the method. Line wraps in the description - # should not be indented. - # - # @return [ Symbol ] For macros, wraps must be double-space indented - # on the second, third, etc. lines. - -- **Whitespace:** Do not use leading/trailing empty comment lines, - or more than one consecutive empty comment line. - - .. code-block:: ruby - - # GOOD: - # @return [ Symbol ] The return value - def my_method - - # BAD: - # @return [ Symbol ] The return value - # - def my_method - - # BAD: - # @param [ Symbol ] foo The input value - # - # - # @return [ Symbol ] The return value - def my_method(foo) - - -.. _code-documentation-type-declaration: - -Type Declaration ----------------- - -- **Type Unions:** Use pipe ``|`` to denote a union of allowed types. - - .. code-block:: ruby - - # @param [ Symbol | String ] name Either a Symbol or a String. - -- **Nested Types:** Use angle brackets ``< >`` to denote type nesting. - - .. code-block:: ruby - - # @param [ Array ] array An Array of symbols. - -- **Hash:** Use comma ``,`` to denote the key and value types. - - .. code-block:: ruby - - # @param [ Hash ] hash A Hash whose keys are Symbols, - # and whose values are Integers. - -- **Array:** Use pipe ``|`` to denote a union of allowed types. - - .. code-block:: ruby - - # @param [ Array ] array An Array whose members must - # be either Symbols or Strings. - -- **Array:** Use comma ``,`` to denote the types of each position in a tuple. - - .. code-block:: ruby - - # @return [ Array ] A 3-member Array whose first - # element is a Symbol, and whose second and third elements are Integers. - -- **Array:** Use pipe ``|`` on the top level if the inner types cannot be - mixed within the Array. - - .. code-block:: ruby - - # @param [ Array | Array ] array An Array containing only - # Symbols, or an Array containing only Hashes. The Array may not contain - # a mix of Symbols and Hashes. - -- **Nested Types:** For clarity, use square brackets ``[ ]`` to denote nested unions - when commas are also used. - - .. code-block:: ruby - - # @param [ Hash ] hash A Hash whose keys are Symbols, - # and whose values are boolean values. - -- **Ruby Values:** Specific values may be denoted in the type using Ruby syntax. - - .. code-block:: ruby - - # @param [ :before | :after ] timing One of the Symbol values :before or :after. - -- **True, False, and Nil:** Use ``true``, ``false``, and ``nil`` rather than - ``TrueClass``, ``FalseClass``, and ``NilClass``. Do not use ``Boolean`` as a type - since it does not exist in Ruby. - - .. code-block:: ruby - - # GOOD: - # @param [ true | false | nil ] bool A boolean or nil value. - - # BAD: - # @param [ TrueClass | FalseClass | NilClass ] bool A boolean or nil value. - # @param [ Boolean ] bool A boolean value. - -- **Return Self:** Specify return value ``self`` where a method returns ``self``. - - .. code-block:: ruby - - # @return [ self ] Returns the object itself. - -- **Splat Args:** Use three-dot ellipses ``...`` in the type declaration and - star ``*`` in the parameter name to denote a splat. - - .. code-block:: ruby - - # @param [ String... ] *items The list of items name(s) as Strings. - def buy_groceries(*items) - -- **Splat Args:** Do not use ``Array`` as the type unless each arg is actually an Array. - - .. code-block:: ruby - - # BAD: - # @param [ Array ] *items The list of items name(s) as Strings. - def buy_groceries(*items) - - buy_groceries("Cheese", "Crackers", "Wine") - - # OK: - # @param [ Array... ] *arrays One or more arrays containing name parts. - def set_people_names(*arrays) - - set_people_names(["Harlan", "Sanders"], ["Jane", "K", ""Doe"], ["Jim", "Beam"]) - -- **Splat Args:** Use comma ``,`` to denote positionality in a splat. - - .. code-block:: ruby - - # @param [ Symbol..., Hash ] *args A list of names, followed by a hash - # as the optional last arg. - def say_hello(*args) - -- **Splat Args:** Specify type unions with square brackets ``[ ]``. - - .. code-block:: ruby - - # @param [ [ String | Symbol ]... ] *fields A splat of mixed Symbols and Strings. - -- **Keyword Arguments:** Following YARD conventions, use ``@param`` for keyword - arguments, and specify keyword argument names as symbols. - - .. code-block:: ruby - - # @param [ String ] query The search string - # @param [ Boolean ] :exact_match Whether to do an exact match - # @param [ Integer ] :results_per_page Number of results - def search(query, exact_match: false, results_per_page: 10) - -- **Hash Options:** Define hash key-value options with ``@option`` macro - immediately following the Hash ``@param``. Note ``@option`` parameter names - are symbols. - - .. code-block:: ruby - - # @param opts [ Hash ] The optional hash argument(s). - # @option opts [ String | Array ] :items The items(s) as Strings to include. - # @option opts [ Integer ] :limit An Integer denoting the limit. - def buy_groceries(opts = {}) - -- **Double Splats:** Use double-star ``**`` in the parameter name to denote a - keyword arg splat (double splat). Note that type does not need declared on - the double-splat element, as it is implicitly . Instead, - define value types with ``@option`` macro below. Note ``@option`` parameter - names are symbols. - - .. code-block:: ruby - - # @param **kwargs The optional keyword argument(s). - # @option **kwargs [ String | Array ] :items The items(s) as Strings to include. - # @option **kwargs [ Integer ] :limit An Integer denoting the limit. - def buy_groceries(**kwargs) - -- **Blocks:** Use ``@yield`` to specify when the method yields to a block. - - .. code-block:: ruby - - # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. - # Must take the person, location, and weapon used. Must return true or false. - def whodunit - yield(:mustard, :ballroom, :candlestick) - end - -- **Blocks:** If the method explicitly specifies a block argument, specify the block - argument using ``@param`` preceded by an ampersand ``&``, and also specify ``@yield``. - Note ``@yield`` should be used even when method calls ``block.call`` rather than - ``yield`` internally. - - .. code-block:: ruby - - # @param &block The block. - # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. - # Must take the person, location, and weapon used. Must return true or false. - def whodunit(&block) - yield(:scarlet, :library, :rope) - end - - # @param &block The block. - # @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime. - # Must take the person, location, and weapon used. Must return true or false. - def whodunit(&block) - block.call(:plum, :kitchen, :pipe) - end - -- **Blocks:** Use ``@yieldparam`` and ``@yieldreturn`` instead of ``@yield`` where - beneficial for clarity. - - .. code-block:: ruby - - # @param &block The block. - # @yieldparam [ Symbol ] The person. - # @yieldparam [ Symbol ] The location. - # @yieldparam [ Symbol ] The weapon used. - # @yieldreturn [ true | false ] Whether the guess is correct. - def whodunit(&block) - yield(:peacock, :conservatory, :wrench) - end - -- **Proc Args:** Proc arguments should use ``@param`` (not ``@yield``). The - inputs to the proc may be specified as subtype(s). - - .. code-block:: ruby - - # @param [ Proc ] my_proc Proc argument which must - # take 3 integers and must return true or false whether the guess is valid. - def guess_three(my_proc) - my_proc.call(42, 7, 88) - end diff --git a/source/contributing/contributing-guidelines.txt b/source/contributing/contributing-guidelines.txt deleted file mode 100644 index 68491bd5..00000000 --- a/source/contributing/contributing-guidelines.txt +++ /dev/null @@ -1,43 +0,0 @@ -.. _contributing-guidelines: - -*********************** -Contributing Guidelines -*********************** - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - - -Contributing Guidelines -======================= - -If you wish to propose an enhancement to Mongoid, please create a Jira ticket -describing the enhancement and what it would enable you to achieve in your -application that is not already possible. If you believe Mongoid is not -behaving correctly, please create a Jira ticket describing how you use Mongoid, -what the existing behavior is that you consider incorrect or problematic, and -what your desired behavior is. If you wish to make changes yourself, the -following guildelines should be followed: - -#. Create a fork of Mongoid. -#. Create a new branch in that fork. -#. Make your changes. -#. Ensure that the proposed changes have adequate test coverage. -#. Raise a PR against Mongoid master. If these changes correspond to a specific - Jira ticket, title the PR: "MONGOID- Description of Changes". -#. The Mongoid team will review the PR and make comments/suggest changes. -#. Once all of the changes and fixes are made, and the Mongoid team determine - the PR fit for merging, we will merge the PR into master and determine - whether it needs to be backported. -#. Backports to previous stable versions are done if the change is a bug fix, - is not backwards breaking, and if the commit is applicable to the - corresponding stable branch. Presently backport candidates would include - versions 7.3-8.0. -#. Changes to 6.0-7.2 are generally not made unless it fixes a security - vulnerability. -#. 5.x and earlier is generally not supported. \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index 75728bb0..90b3eb5d 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,12 +18,10 @@ MongoDB in Ruby. To work with {+odm+} from the command line using Interact with Data Model Your Data Configuration - .. installation-configuration - .. tutorials - .. schema-configuration - working-with-data + /working-with-data API /release-notes + Issues & Help /contributing /additional-resources /ecosystem diff --git a/source/issues-and-help.txt b/source/issues-and-help.txt new file mode 100644 index 00000000..14b6ab4f --- /dev/null +++ b/source/issues-and-help.txt @@ -0,0 +1,85 @@ +.. _mongoid-issues-and-help: + +============= +Issues & Help +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: mongoid, ruby, troubleshooting, feedback + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. toctree:: + :titlesonly: + + Code Documentation + +We are lucky to have a vibrant MongoDB {+language+} community that includes users +with varying levels of experience using {+odm+} and the {+ruby-driver+}. +The quickest way to get support for general questions is through the +:community-forum:`MongoDB Community Forums `. + +Bugs / Feature Requests +----------------------- + +If you have feedback about {+odm+}, visit the `MongoDB +Feedback Engine `__ and select +:guilabel:`Drivers` from the list of products on the right side of +your screen. You can propose improvements, report issues, and provide +other types of feedback by using this site. + +You can also open a case in Jira, our issue management tool, to identify +bugs or propose improvements. The following steps describe how to create +a Jira issue: + +1. Visit the `MongoDB Jira issue tracker `__ and click the + `signup link. `__ + Create an account, and then log in to Jira. +#. Navigate to the `MONGOID Jira project. `__ +#. Click :guilabel:`Create` to create a ticket. Please provide as much + information as possible about the issue or request in the ticket. + +.. note:: + + Bug reports in the MONGOID Jira project are publicly viewable. + +If you’ve identified a security vulnerability in any official MongoDB +product, please report it according to the instructions found in the +:manual:`Create a Vulnerability Report +` guide. + +Pull Requests +------------- + +We are happy to accept contributions to help improve the driver. We will guide +user contributions to ensure they meet the standards of the codebase. Please +ensure that any pull requests include documentation, tests, and pass +code checks. To learn about {+odm+}'s code documentation conventions, +see the :ref:`mongoid-code-documentation` guide. + +To get started, clone the source repository and work on a branch by +running the following commands: + +.. code-block:: bash + + git clone https://github.com/mongodb/mongoid.git + cd mongoid + git checkout -b my-new-feature + +.. tip:: + + If your changes correspond to a specific Jira ticket, title your pull + request by using the following convention: + + ``MONGOID-: `` + +The {+odm+} developer team then will review your pull request and make +comments or suggest changes. From ad035bc483a0a3e83645ddde279493c498fa242f Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 11:53:25 -0500 Subject: [PATCH 2/5] remove contributing --- source/index.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/source/index.txt b/source/index.txt index 90b3eb5d..0bb10fa9 100644 --- a/source/index.txt +++ b/source/index.txt @@ -22,6 +22,5 @@ MongoDB in Ruby. To work with {+odm+} from the command line using API /release-notes Issues & Help - /contributing /additional-resources /ecosystem From 5784ddd0537a8b9ba8ee844ebe7509b1a9ac7bf6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 11:55:25 -0500 Subject: [PATCH 3/5] vale fixes --- source/code-documentation.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/code-documentation.txt b/source/code-documentation.txt index 59d692bc..9f08d92c 100644 --- a/source/code-documentation.txt +++ b/source/code-documentation.txt @@ -26,7 +26,7 @@ documentation tool, for its code documentation. Structure --------- -- **Modules:** All class and module definitions should be preceded by +- **Modules:** All class and module definitions must be preceded by a documentation comment. .. code-block:: ruby @@ -35,7 +35,7 @@ Structure # what they do with corrugated cardboard these days. class CardboardBox -- **Methods:** All method definitions should be preceded by a +- **Methods:** All method definitions must be preceded by a documentation comment. Use ``@param``, ``@yield``, and ``@return`` to specify inputs and output. To learn more, see the :ref:`mongoid-code-documentation-type-declaration` section. @@ -70,7 +70,7 @@ Structure def do_something_obvious - **API Private:** Classes and public methods which are not intended for - external usage should be marked ``@api private``. This macro does not + external usage must be marked ``@api private``. This macro does not require a comment. Note that, because {+odm+}'s modules are mixed into application classes, @@ -117,7 +117,7 @@ Formatting .. code-block:: ruby # This is the description of the method. Line wraps in the description - # should not be indented. + # must not be indented. # # @return [ Symbol ] For macros, wraps must be double-space indented # on the second, third, etc. lines. @@ -307,7 +307,7 @@ Type Declaration - **Blocks:** If the method explicitly specifies a block argument, specify the block argument using ``@param`` preceded by an ampersand ``&``, and also specify ``@yield``. - Note ``@yield`` should be used even when method calls ``block.call`` rather than + Note ``@yield`` must be used even when method calls ``block.call`` rather than ``yield`` internally. .. code-block:: ruby @@ -340,7 +340,7 @@ Type Declaration yield(:peacock, :conservatory, :wrench) end -- **Proc Args:** Proc arguments should use ``@param`` (not ``@yield``). The +- **Proc Args:** Proc arguments must use ``@param`` (not ``@yield``). The inputs to the proc may be specified as subtype(s). .. code-block:: ruby From c01b8d0325e6887f69a9053b68810d32b59a187a Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 12:01:38 -0500 Subject: [PATCH 4/5] link fix --- source/issues-and-help.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/issues-and-help.txt b/source/issues-and-help.txt index 14b6ab4f..7b19a3af 100644 --- a/source/issues-and-help.txt +++ b/source/issues-and-help.txt @@ -25,7 +25,7 @@ Issues & Help We are lucky to have a vibrant MongoDB {+language+} community that includes users with varying levels of experience using {+odm+} and the {+ruby-driver+}. The quickest way to get support for general questions is through the -:community-forum:`MongoDB Community Forums `. +:community-forum:`MongoDB Community Forums `. Bugs / Feature Requests ----------------------- @@ -81,5 +81,5 @@ running the following commands: ``MONGOID-: `` -The {+odm+} developer team then will review your pull request and make +The {+odm+} developer team will review your pull request and make comments or suggest changes. From a6d97d228d63526ed1a046eccbbe23d63e411ba3 Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 15 Jan 2025 13:29:12 -0500 Subject: [PATCH 5/5] vale fixes + RM comment --- source/code-documentation.txt | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/source/code-documentation.txt b/source/code-documentation.txt index 9f08d92c..dd18d384 100644 --- a/source/code-documentation.txt +++ b/source/code-documentation.txt @@ -120,23 +120,23 @@ Formatting # must not be indented. # # @return [ Symbol ] For macros, wraps must be double-space indented - # on the second, third, etc. lines. + # on the second, third (and so on) lines. - **Whitespace:** Do not use leading/trailing empty comment lines, or more than one consecutive empty comment line. .. code-block:: ruby - # GOOD: + # DO THIS: # @return [ Symbol ] The return value def my_method - # BAD: + # NOT THIS: # @return [ Symbol ] The return value # def my_method - # BAD: + # NOT THIS: # @param [ Symbol ] foo The input value # # @@ -210,10 +210,10 @@ Type Declaration .. code-block:: ruby - # GOOD: + # DO THIS: # @param [ true | false | nil ] bool A boolean or nil value. - # BAD: + # NOT THIS: # @param [ TrueClass | FalseClass | NilClass ] bool A boolean or nil value. # @param [ Boolean ] bool A boolean value. @@ -228,20 +228,20 @@ Type Declaration .. code-block:: ruby - # @param [ String... ] *items The list of items name(s) as Strings. + # @param [ String... ] *items The list of items' names as Strings. def buy_groceries(*items) - **Splat Args:** Do not use ``Array`` as the type unless each arg is actually an Array. .. code-block:: ruby - # BAD: - # @param [ Array ] *items The list of items name(s) as Strings. + # DO NOT DO THIS: + # @param [ Array ] *items The list of items' names as Strings. def buy_groceries(*items) buy_groceries("Cheese", "Crackers", "Wine") - # OK: + # DO THIS: # @param [ Array... ] *arrays One or more arrays containing name parts. def set_people_names(*arrays) @@ -277,8 +277,8 @@ Type Declaration .. code-block:: ruby - # @param opts [ Hash ] The optional hash argument(s). - # @option opts [ String | Array ] :items The items(s) as Strings to include. + # @param opts [ Hash ] The optional hash argument or arguments. + # @option opts [ String | Array ] :items The items as Strings to include. # @option opts [ Integer ] :limit An Integer denoting the limit. def buy_groceries(opts = {}) @@ -290,8 +290,8 @@ Type Declaration .. code-block:: ruby - # @param **kwargs The optional keyword argument(s). - # @option **kwargs [ String | Array ] :items The items(s) as Strings to include. + # @param **kwargs The optional keyword argument or arguments. + # @option **kwargs [ String | Array ] :items The items as Strings to include. # @option **kwargs [ Integer ] :limit An Integer denoting the limit. def buy_groceries(**kwargs) @@ -340,8 +340,8 @@ Type Declaration yield(:peacock, :conservatory, :wrench) end -- **Proc Args:** Proc arguments must use ``@param`` (not ``@yield``). The - inputs to the proc may be specified as subtype(s). +- **Proc Args:** Use ``@param`` (not ``@yield``) for proc arguments. The + inputs to the proc may be specified as subtypes. .. code-block:: ruby