Skip to content

Commit ea217ed

Browse files
johnnyshieldsjohnnyshields
committed
Code Docs: Make it a rule to use full namespaces in code doc. This avoids ambiguity for example between Mongoid::Document and BSON::Document.
This PR includes the change for the following classes: - Mongoid::Document - Mongoid::Criteria - Mongoid::Association::Proxy - Mongoid::Criteria::Queryable Any stragglers missed can be fixed on an ongoing basis.
1 parent eac948c commit ea217ed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

94 files changed

+454
-429
lines changed

‎docs/contributing/code-documentation.txt

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,31 @@ Formatting
149149
Type Declaration
150150
----------------
151151

152+
- **Namespaces:** Always use fully-namespaced class/module names.
153+
Do not use leading colons ``::``.
154+
155+
.. code-block:: ruby
156+
157+
# GOOD:
158+
# @param [ ActiveSupport::TimeWithZone ] time Time for alarm.
159+
160+
# BAD:
161+
# @param [ TimeWithZone ] time Time for alarm.
162+
# @param [ ::ActiveSupport::TimeWithZone ] time Time for alarm.
163+
164+
- **Module Types:** It is acceptable to reference types by a module
165+
which they include.
166+
167+
.. code-block:: ruby
168+
169+
class Person
170+
include ActiveModel::Model
171+
end
172+
173+
# @param [ ActiveModel::Model ] model Any object whose class
174+
# includes ActiveModel::Model. An instance of Person would
175+
# be acceptable here.
176+
152177
- **Type Unions:** Use pipe ``|`` to denote a union of allowed types.
153178

154179
.. code-block:: ruby

‎lib/mongoid/association/accessors.rb

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ module Accessors
2222
# If selected_fields is specified, fields not listed in it will not be
2323
# accessible in the built document.
2424
#
25-
# @return [ Proxy ] The association.
25+
# @return [ Mongoid::Association::Proxy ] The association.
2626
def __build__(name, object, association, selected_fields = nil)
2727
relation = create_relation(object, association, selected_fields)
2828
set_relation(name, relation)
@@ -33,13 +33,13 @@ def __build__(name, object, association, selected_fields = nil)
3333
# @example Create the association.
3434
# person.create_relation(document, association)
3535
#
36-
# @param [ Document | Array<Document> ] object The association target.
36+
# @param [ Mongoid::Document | Array<Mongoid::Document> ] object The association target.
3737
# @param [ Mongoid::Association::Relatable ] association The association metadata.
3838
# @param [ Hash ] selected_fields Fields which were retrieved via #only.
3939
# If selected_fields is specified, fields not listed in it will not be
4040
# accessible in the created association document.
4141
#
42-
# @return [ Proxy ] The association.
42+
# @return [ Mongoid::Association::Proxy ] The association.
4343
def create_relation(object, association, selected_fields = nil)
4444
type = @attributes[association.inverse_type]
4545
target = if t = association.build(self, object, type, selected_fields)
@@ -81,9 +81,9 @@ def reset_relation_criteria(name)
8181
# person.set(:addresses, addresses)
8282
#
8383
# @param [ String | Symbol ] name The name of the association.
84-
# @param [ Proxy ] relation The association to set.
84+
# @param [ Mongoid::Association::Proxy ] relation The association to set.
8585
#
86-
# @return [ Proxy ] The association.
86+
# @return [ Mongoid::Association::Proxy ] The association.
8787
def set_relation(name, relation)
8888
instance_variable_set("@_#{name}", relation)
8989
end
@@ -103,7 +103,7 @@ def set_relation(name, relation)
103103
# @param [ Object ] object The object used to build the association.
104104
# @param [ true | false ] reload If the association is to be reloaded.
105105
#
106-
# @return [ Proxy ] The association.
106+
# @return [ Mongoid::Association::Proxy ] The association.
107107
def get_relation(name, association, object, reload = false)
108108
field_name = database_field_name(name)
109109

‎lib/mongoid/association/bindable.rb

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ module Bindable
1414
# @example Initialize a binding.
1515
# Binding.new(base, target, association)
1616
#
17-
# @param [ Document ] base The base of the binding.
18-
# @param [ Document | Array<Document> ] target The target of the binding.
17+
# @param [ Mongoid::Document ] base The base of the binding.
18+
# @param [ Mongoid::Document | Array<Mongoid::Document> ] target The target of the binding.
1919
# @param [ Mongoid::Association::Relatable ] association The association metadata.
2020
def initialize(base, target, association)
2121
@_base, @_target, @_association = base, target, association
@@ -46,7 +46,7 @@ def binding
4646
# @example Check the inverse definition.
4747
# binding.check_inverse!(doc)
4848
#
49-
# @param [ Document ] doc The document getting bound.
49+
# @param [ Mongoid::Document ] doc The document getting bound.
5050
#
5151
# @raise [ Errors::InverseNotFound ] If no inverse found.
5252
def check_inverse!(doc)
@@ -62,7 +62,7 @@ def check_inverse!(doc)
6262

6363
# Remove the associated document from the inverse's association.
6464
#
65-
# @param [ Document ] doc The document to remove.
65+
# @param [ Mongoid::Document ] doc The document to remove.
6666
def remove_associated(doc)
6767
if inverse = _association.inverse(doc)
6868
if _association.many?
@@ -77,7 +77,7 @@ def remove_associated(doc)
7777
#
7878
# This method removes the associated on *_many relationships.
7979
#
80-
# @param [ Document ] doc The document to remove.
80+
# @param [ Mongoid::Document ] doc The document to remove.
8181
# @param [ Symbol ] inverse The name of the inverse.
8282
def remove_associated_many(doc, inverse)
8383
# We only want to remove the inverse association when the inverse
@@ -97,7 +97,7 @@ def remove_associated_many(doc, inverse)
9797
# This method removes associated on belongs_to and embedded_in
9898
# associations.
9999
#
100-
# @param [ Document ] doc The document to remove.
100+
# @param [ Mongoid::Document ] doc The document to remove.
101101
# @param [ Symbol ] inverse The name of the inverse.
102102
def remove_associated_in_to(doc, inverse)
103103
# We only want to remove the inverse association when the inverse
@@ -115,7 +115,7 @@ def remove_associated_in_to(doc, inverse)
115115
# @example Bind the foreign key.
116116
# binding.bind_foreign_key(post, person._id)
117117
#
118-
# @param [ Document ] keyed The document that stores the foreign key.
118+
# @param [ Mongoid::Document ] keyed The document that stores the foreign key.
119119
# @param [ Object ] id The id of the bound document.
120120
def bind_foreign_key(keyed, id)
121121
unless keyed.frozen?
@@ -131,7 +131,7 @@ def bind_foreign_key(keyed, id)
131131
# @example Bind the polymorphic type.
132132
# binding.bind_polymorphic_type(post, "Person")
133133
#
134-
# @param [ Document ] typed The document that stores the type field.
134+
# @param [ Mongoid::Document ] typed The document that stores the type field.
135135
# @param [ String ] name The name of the model.
136136
def bind_polymorphic_type(typed, name)
137137
if _association.type
@@ -147,7 +147,7 @@ def bind_polymorphic_type(typed, name)
147147
# @example Bind the polymorphic type.
148148
# binding.bind_polymorphic_inverse_type(post, "Person")
149149
#
150-
# @param [ Document ] typed The document that stores the type field.
150+
# @param [ Mongoid::Document ] typed The document that stores the type field.
151151
# @param [ String ] name The name of the model.
152152
def bind_polymorphic_inverse_type(typed, name)
153153
if _association.inverse_type
@@ -163,8 +163,8 @@ def bind_polymorphic_inverse_type(typed, name)
163163
# @example Bind the inverse.
164164
# binding.bind_inverse(post, person)
165165
#
166-
# @param [ Document ] doc The base document.
167-
# @param [ Document ] inverse The inverse document.
166+
# @param [ Mongoid::Document ] doc The base document.
167+
# @param [ Mongoid::Document ] inverse The inverse document.
168168
def bind_inverse(doc, inverse)
169169
if doc.respond_to?(_association.inverse_setter)
170170
doc.you_must(_association.inverse_setter, inverse)
@@ -178,7 +178,7 @@ def bind_inverse(doc, inverse)
178178
# @example Bind the document with the base.
179179
# binding.bind_from_relational_parent(doc)
180180
#
181-
# @param [ Document ] doc The document to bind.
181+
# @param [ Mongoid::Document ] doc The document to bind.
182182
def bind_from_relational_parent(doc)
183183
check_inverse!(doc)
184184
remove_associated(doc)
@@ -215,7 +215,7 @@ def set_base_association
215215
# @example Bind the document with the base.
216216
# unbinding.unbind_from_relational_parent(doc)
217217
#
218-
# @param [ Document ] doc The document to unbind.
218+
# @param [ Mongoid::Document ] doc The document to unbind.
219219
def unbind_from_relational_parent(doc)
220220
check_inverse!(doc)
221221
bind_foreign_key(doc, nil)

‎lib/mongoid/association/eager_loadable.rb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ def eager_load(docs)
2626
#
2727
# @param [ Array<Mongoid::Association::Relatable> ] associations
2828
# The associations to load.
29-
# @param [ Array<Document> ] document The documents.
29+
# @param [ Array<Mongoid::Document> ] document The documents.
3030
def preload(associations, docs)
3131
assoc_map = associations.group_by(&:inverse_class_name)
3232
docs_map = {}

‎lib/mongoid/association/embedded/batchable.rb

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ module Batchable
1616
# @example Execute the batch push.
1717
# batchable.batch_insert([ doc_one, doc_two ])
1818
#
19-
# @param [ Array<Document> ] docs The docs to add.
19+
# @param [ Array<Mongoid::Document> ] docs The docs to add.
2020
#
2121
# @return [ Array<Hash> ] The inserts.
2222
def batch_insert(docs)
@@ -28,7 +28,7 @@ def batch_insert(docs)
2828
# @example Clear all docs.
2929
# batchable.batch_clear(docs)
3030
#
31-
# @param [ Array<Document> ] docs The docs to clear.
31+
# @param [ Array<Mongoid::Document> ] docs The docs to clear.
3232
#
3333
# @return [ Array ] The empty array.
3434
def batch_clear(docs)
@@ -55,7 +55,7 @@ def batch_clear(docs)
5555
# @example Batch remove the documents.
5656
# batchable.batch_remove([ doc_one, doc_two ])
5757
#
58-
# @param [ Array<Document> ] docs The docs to remove.
58+
# @param [ Array<Mongoid::Document> ] docs The docs to remove.
5959
# @param [ Symbol ] method Delete or destroy.
6060
def batch_remove(docs, method = :delete)
6161
# If the _id is nil, we cannot use $pull and delete by searching for
@@ -97,7 +97,7 @@ def batch_remove(docs, method = :delete)
9797
# @example Batch replace the documents.
9898
# batchable.batch_replace([ doc_one, doc_two ])
9999
#
100-
# @param [ Array<Document> | Array<Hash> ] docs The docs to replace with.
100+
# @param [ Array<Mongoid::Document> | Array<Hash> ] docs The docs to replace with.
101101
#
102102
# @return [ Array<Hash> ] The inserts.
103103
def batch_replace(docs)
@@ -150,7 +150,7 @@ def add_atomic_sets(sets)
150150
# @example Perform a batch $set.
151151
# batchable.execute_batch_set(docs)
152152
#
153-
# @param [ Array<Document> ] docs The docs to persist.
153+
# @param [ Array<Mongoid::Document> ] docs The docs to persist.
154154
#
155155
# @return [ Array<Hash> ] The inserts.
156156
def execute_batch_set(docs)
@@ -173,7 +173,7 @@ def execute_batch_set(docs)
173173
# @example Perform a batch push.
174174
# batchable.execute_batch_push(docs)
175175
#
176-
# @param [ Array<Document> ] docs The docs to persist.
176+
# @param [ Array<Mongoid::Document> ] docs The docs to persist.
177177
#
178178
# @return [ Array<Hash> ] The inserts.
179179
def execute_batch_push(docs)
@@ -235,9 +235,9 @@ def inserts_valid=(value)
235235
# @example Normalize the docs.
236236
# batchable.normalize_docs(docs)
237237
#
238-
# @param [ Array<Document> | Array<Hash> ] docs The docs to normalize.
238+
# @param [ Array<Mongoid::Document> | Array<Hash> ] docs The docs to normalize.
239239
#
240-
# @return [ Array<Document> ] The docs.
240+
# @return [ Array<Mongoid::Document> ] The docs.
241241
def normalize_docs(docs)
242242
if docs.first.is_a?(::Hash)
243243
docs.map do |doc|
@@ -310,7 +310,7 @@ def selector
310310
# @example Pre process the documents.
311311
# batchable.pre_process_batch_insert(docs)
312312
#
313-
# @param [ Array<Document> ] docs The documents.
313+
# @param [ Array<Mongoid::Document> ] docs The documents.
314314
#
315315
# @return [ Array<Hash> ] The documents as an array of hashes.
316316
def pre_process_batch_insert(docs)
@@ -336,7 +336,7 @@ def pre_process_batch_insert(docs)
336336
# @example Pre process the documents.
337337
# batchable.pre_process_batch_remove(docs, :delete)
338338
#
339-
# @param [ Array<Document> ] docs The documents.
339+
# @param [ Array<Mongoid::Document> ] docs The documents.
340340
# @param [ Symbol ] method Delete or destroy.
341341
#
342342
# @return [ Array<Hash> ] The documents as hashes.
@@ -363,7 +363,7 @@ def pre_process_batch_remove(docs, method)
363363
# @example Post process the documents.
364364
# batchable.post_process_batch_insert(docs)
365365
#
366-
# @param [ Array<Documents> ] docs The inserted docs.
366+
# @param [ Array<Mongoid::Document> ] docs The inserted docs.
367367
#
368368
# @return [ Enumerable ] The document enum.
369369
def post_process_batch_insert(docs)
@@ -381,10 +381,10 @@ def post_process_batch_insert(docs)
381381
# @example Post process the documents.
382382
# batchable.post_process_batch_remove(docs, :delete)
383383
#
384-
# @param [ Array<Document> ] docs The documents.
384+
# @param [ Array<Mongoid::Document> ] docs The documents.
385385
# @param [ Symbol ] method Delete or destroy.
386386
#
387-
# @return [ Array<Document> ] The documents.
387+
# @return [ Array<Mongoid::Document> ] The documents.
388388
def post_process_batch_remove(docs, method)
389389
docs.each do |doc|
390390
doc.run_after_callbacks(:destroy) if method == :destroy

‎lib/mongoid/association/embedded/embedded_in/binding.rb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ def unbind_one
5757
# @example Check for inverses errors.
5858
# binding.check_inverses!(doc)
5959
#
60-
# @param [ Document ] doc The document to check.
60+
# @param [ Mongoid::Document ] doc The document to check.
6161
def check_polymorphic_inverses!(doc)
6262
if inverses = _association.inverses(doc)
6363
if inverses.length > 1

‎lib/mongoid/association/embedded/embedded_in/buildable.rb

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,14 @@ module Buildable
1515
# @example Build the document.
1616
# Builder.new(meta, attrs).build
1717
#
18-
# @param [ Document ] base The object.
19-
# @param [ Document | Hash ] object The parent hash or document.
18+
# @param [ Mongoid::Document ] base The object.
19+
# @param [ Mongoid::Document | Hash ] object The parent hash or document.
2020
# @param [ String ] type Not used in this context.
2121
# @param [ Hash ] selected_fields Fields which were retrieved via
2222
# #only. If selected_fields are specified, fields not listed in it
2323
# will not be accessible in the built document.
2424
#
25-
# @return [ Document ] A single document.
25+
# @return [ Mongoid::Document ] A single document.
2626
def build(base, object, type = nil, selected_fields = nil)
2727
return object unless object.is_a?(Hash)
2828
if _loading?

‎lib/mongoid/association/embedded/embedded_in/proxy.rb

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ class Proxy < Association::One
1212
# @example Create the new association.
1313
# Association::Embedded::EmbeddedIn.new(person, address, association)
1414
#
15-
# @param [ Document ] base The document the association hangs off of.
16-
# @param [ Document ] target The target (parent) of the association.
15+
# @param [ Mongoid::Document ] base The document the association hangs off of.
16+
# @param [ Mongoid::Document ] target The target (parent) of the association.
1717
# @param [ Mongoid::Association::Relatable ] association The association metadata.
1818
#
1919
# @return [ In ] The proxy.
@@ -30,9 +30,9 @@ def initialize(base, target, association)
3030
# @example Substitute the new document.
3131
# person.name.substitute(new_name)
3232
#
33-
# @param [ Document | Hash ] replacement A document to replace the target.
33+
# @param [ Mongoid::Document | Hash ] replacement A document to replace the target.
3434
#
35-
# @return [ Document | nil ] The association or nil.
35+
# @return [ Mongoid::Document | nil ] The association or nil.
3636
def substitute(replacement)
3737
unbind_one
3838
unless replacement
@@ -63,7 +63,7 @@ def binding
6363
# @example Set the base association.
6464
# object.characterize_one(document)
6565
#
66-
# @param [ Document ] document The document to set the association metadata on.
66+
# @param [ Mongoid::Document ] document The document to set the association metadata on.
6767
def characterize_one(document)
6868
unless _base._association
6969
_base._association = _association.inverse_association(document)
@@ -98,7 +98,7 @@ def embedded?
9898
# @example Get the path calculator.
9999
# Proxy.path(document)
100100
#
101-
# @param [ Document ] document The document to calculate on.
101+
# @param [ Mongoid::Document ] document The document to calculate on.
102102
#
103103
# @return [ Root ] The root atomic path calculator.
104104
def path(document)

‎lib/mongoid/association/embedded/embeds_many.rb

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ def nested_builder(attributes, options)
121121
# @example Get the path calculator.
122122
# Proxy.path(document)
123123
#
124-
# @param [ Document ] document The document to calculate on.
124+
# @param [ Mongoid::Document ] document The document to calculate on.
125125
#
126126
# @return [ Mongoid::Atomic::Paths::Embedded::Many ]
127127
# The embedded many atomic path calculator.
@@ -131,8 +131,8 @@ def path(document)
131131

132132
# Get a criteria object for searching given a parent and children documents.
133133
#
134-
# @param [ Document ] base The base document.
135-
# @param [ Document ] target The children documents.
134+
# @param [ Mongoid::Document ] base The base document.
135+
# @param [ Mongoid::Document ] target The children documents.
136136
def criteria(base, target)
137137
criterion = klass.scoped
138138
criterion.embedded = true

0 commit comments

Comments
 (0)