Skip to content

Commit e68482e

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 1c77b9d commit e68482e

Some content is hidden

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

92 files changed

+459
-432
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
@@ -23,7 +23,7 @@ module Accessors
2323
# If selected_fields is specified, fields not listed in it will not be
2424
# accessible in the built document.
2525
#
26-
# @return [ Proxy ] The association.
26+
# @return [ Mongoid::Association::Proxy ] The association.
2727
def __build__(name, object, association, selected_fields = nil)
2828
relation = create_relation(object, association, selected_fields)
2929
set_relation(name, relation)
@@ -34,13 +34,13 @@ def __build__(name, object, association, selected_fields = nil)
3434
# @example Create the association.
3535
# person.create_relation(document, association)
3636
#
37-
# @param [ Document | Array<Document> ] object The association target.
37+
# @param [ Mongoid::Document | Array<Mongoid::Document> ] object The association target.
3838
# @param [ Mongoid::Association::Relatable ] association The association metadata.
3939
# @param [ Hash ] selected_fields Fields which were retrieved via #only.
4040
# If selected_fields is specified, fields not listed in it will not be
4141
# accessible in the created association document.
4242
#
43-
# @return [ Proxy ] The association.
43+
# @return [ Mongoid::Association::Proxy ] The association.
4444
def create_relation(object, association, selected_fields = nil)
4545
type = @attributes[association.inverse_type]
4646
target = if t = association.build(self, object, type, selected_fields)
@@ -82,9 +82,9 @@ def reset_relation_criteria(name)
8282
# person.set(:addresses, addresses)
8383
#
8484
# @param [ String | Symbol ] name The name of the association.
85-
# @param [ Proxy ] relation The association to set.
85+
# @param [ Mongoid::Association::Proxy ] relation The association to set.
8686
#
87-
# @return [ Proxy ] The association.
87+
# @return [ Mongoid::Association::Proxy ] The association.
8888
def set_relation(name, relation)
8989
instance_variable_set("@_#{name}", relation)
9090
end
@@ -104,7 +104,7 @@ def set_relation(name, relation)
104104
# @param [ Object ] object The object used to build the association.
105105
# @param [ true | false ] reload If the association is to be reloaded.
106106
#
107-
# @return [ Proxy ] The association.
107+
# @return [ Mongoid::Association::Proxy ] The association.
108108
def get_relation(name, association, object, reload = false)
109109
field_name = database_field_name(name)
110110

‎lib/mongoid/association/bindable.rb‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ module Bindable
1515
# @example Initialize a binding.
1616
# Binding.new(base, target, association)
1717
#
18-
# @param [ Document ] base The base of the binding.
19-
# @param [ Document | Array<Document> ] target The target of the binding.
18+
# @param [ Mongoid::Document ] base The base of the binding.
19+
# @param [ Mongoid::Document | Array<Mongoid::Document> ] target The target of the binding.
2020
# @param [ Mongoid::Association::Relatable ] association The association metadata.
2121
def initialize(base, target, association)
2222
@_base, @_target, @_association = base, target, association
@@ -47,7 +47,7 @@ def binding
4747
# @example Check the inverse definition.
4848
# binding.check_inverse!(doc)
4949
#
50-
# @param [ Document ] doc The document getting bound.
50+
# @param [ Mongoid::Document ] doc The document getting bound.
5151
#
5252
# @raise [ Errors::InverseNotFound ] If no inverse found.
5353
def check_inverse!(doc)
@@ -63,7 +63,7 @@ def check_inverse!(doc)
6363

6464
# Remove the associated document from the inverse's association.
6565
#
66-
# @param [ Document ] doc The document to remove.
66+
# @param [ Mongoid::Document ] doc The document to remove.
6767
def remove_associated(doc)
6868
if inverse = _association.inverse(doc)
6969
if _association.many?
@@ -78,7 +78,7 @@ def remove_associated(doc)
7878
#
7979
# This method removes the associated on *_many relationships.
8080
#
81-
# @param [ Document ] doc The document to remove.
81+
# @param [ Mongoid::Document ] doc The document to remove.
8282
# @param [ Symbol ] inverse The name of the inverse.
8383
def remove_associated_many(doc, inverse)
8484
# We only want to remove the inverse association when the inverse
@@ -98,7 +98,7 @@ def remove_associated_many(doc, inverse)
9898
# This method removes associated on belongs_to and embedded_in
9999
# associations.
100100
#
101-
# @param [ Document ] doc The document to remove.
101+
# @param [ Mongoid::Document ] doc The document to remove.
102102
# @param [ Symbol ] inverse The name of the inverse.
103103
def remove_associated_in_to(doc, inverse)
104104
# We only want to remove the inverse association when the inverse
@@ -116,7 +116,7 @@ def remove_associated_in_to(doc, inverse)
116116
# @example Bind the foreign key.
117117
# binding.bind_foreign_key(post, person._id)
118118
#
119-
# @param [ Document ] keyed The document that stores the foreign key.
119+
# @param [ Mongoid::Document ] keyed The document that stores the foreign key.
120120
# @param [ Object ] id The id of the bound document.
121121
def bind_foreign_key(keyed, id)
122122
unless keyed.frozen?
@@ -132,7 +132,7 @@ def bind_foreign_key(keyed, id)
132132
# @example Bind the polymorphic type.
133133
# binding.bind_polymorphic_type(post, "Person")
134134
#
135-
# @param [ Document ] typed The document that stores the type field.
135+
# @param [ Mongoid::Document ] typed The document that stores the type field.
136136
# @param [ String ] name The name of the model.
137137
def bind_polymorphic_type(typed, name)
138138
if _association.type && !typed.frozen?
@@ -148,7 +148,7 @@ def bind_polymorphic_type(typed, name)
148148
# @example Bind the polymorphic type.
149149
# binding.bind_polymorphic_inverse_type(post, "Person")
150150
#
151-
# @param [ Document ] typed The document that stores the type field.
151+
# @param [ Mongoid::Document ] typed The document that stores the type field.
152152
# @param [ String ] name The name of the model.
153153
def bind_polymorphic_inverse_type(typed, name)
154154
if _association.inverse_type && !typed.frozen?
@@ -164,8 +164,8 @@ def bind_polymorphic_inverse_type(typed, name)
164164
# @example Bind the inverse.
165165
# binding.bind_inverse(post, person)
166166
#
167-
# @param [ Document ] doc The base document.
168-
# @param [ Document ] inverse The inverse document.
167+
# @param [ Mongoid::Document ] doc The base document.
168+
# @param [ Mongoid::Document ] inverse The inverse document.
169169
def bind_inverse(doc, inverse)
170170
if doc.respond_to?(_association.inverse_setter) && !doc.frozen?
171171
try_method(doc, _association.inverse_setter, inverse)
@@ -179,7 +179,7 @@ def bind_inverse(doc, inverse)
179179
# @example Bind the document with the base.
180180
# binding.bind_from_relational_parent(doc)
181181
#
182-
# @param [ Document ] doc The document to bind.
182+
# @param [ Mongoid::Document ] doc The document to bind.
183183
def bind_from_relational_parent(doc)
184184
check_inverse!(doc)
185185
remove_associated(doc)
@@ -216,7 +216,7 @@ def set_base_association
216216
# @example Bind the document with the base.
217217
# unbinding.unbind_from_relational_parent(doc)
218218
#
219-
# @param [ Document ] doc The document to unbind.
219+
# @param [ Mongoid::Document ] doc The document to unbind.
220220
def unbind_from_relational_parent(doc)
221221
check_inverse!(doc)
222222
bind_foreign_key(doc, nil)

‎lib/mongoid/association/eager.rb‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ class Eager
1313
#
1414
# @param [ Array<Mongoid::Association::Relatable> ] associations
1515
# Associations to eager load
16-
# @param [ Array<Document> ] docs Documents to preload the associations
16+
# @param [ Array<Mongoid::Document> ] docs Documents to preload the associations
1717
#
1818
# @return [ Base ] The eager load preloader
1919
def initialize(associations, docs)
@@ -84,7 +84,7 @@ def each_loaded_document(&block)
8484
# loader.set_on_parent("foo", docs)
8585
#
8686
# @param [ ObjectId ] id parent`s id
87-
# @param [ Document | Array ] element to push into the parent
87+
# @param [ Mongoid::Document | Array ] element to push into the parent
8888
def set_on_parent(id, element)
8989
grouped_docs[id].each do |d|
9090
set_relation(d, element)
@@ -138,8 +138,8 @@ def group_by_key
138138
# @example Set docs into parent using the current association name.
139139
# loader.set_relation(doc, docs)
140140
#
141-
# @param [ Document ] doc The object to set the association on
142-
# @param [ Document | Array ] element to set into the parent
141+
# @param [ Mongoid::Document ] doc The object to set the association on
142+
# @param [ Mongoid::Document | Array ] element to set into the parent
143143
def set_relation(doc, element)
144144
doc.set_relation(@association.name, element) unless doc.blank?
145145
end

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

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ module Batchable
1717
# @example Execute the batch push.
1818
# batchable.batch_insert([ doc_one, doc_two ])
1919
#
20-
# @param [ Array<Document> ] docs The docs to add.
20+
# @param [ Array<Mongoid::Document> ] docs The docs to add.
2121
#
2222
# @return [ Array<Hash> ] The inserts.
2323
def batch_insert(docs)
@@ -29,7 +29,7 @@ def batch_insert(docs)
2929
# @example Clear all docs.
3030
# batchable.batch_clear(docs)
3131
#
32-
# @param [ Array<Document> ] docs The docs to clear.
32+
# @param [ Array<Mongoid::Document> ] docs The docs to clear.
3333
#
3434
# @return [ Array ] The empty array.
3535
def batch_clear(docs)
@@ -54,7 +54,7 @@ def batch_clear(docs)
5454
# @example Batch remove the documents.
5555
# batchable.batch_remove([ doc_one, doc_two ])
5656
#
57-
# @param [ Array<Document> ] docs The docs to remove.
57+
# @param [ Array<Mongoid::Document> ] docs The docs to remove.
5858
# @param [ Symbol ] method Delete or destroy.
5959
def batch_remove(docs, method = :delete)
6060
# If the _id is nil, we cannot use $pull and delete by searching for
@@ -96,7 +96,7 @@ def batch_remove(docs, method = :delete)
9696
# @example Batch replace the documents.
9797
# batchable.batch_replace([ doc_one, doc_two ])
9898
#
99-
# @param [ Array<Document> | Array<Hash> ] docs The docs to replace with.
99+
# @param [ Array<Mongoid::Document> | Array<Hash> ] docs The docs to replace with.
100100
#
101101
# @return [ Array<Hash> ] The inserts.
102102
def batch_replace(docs)
@@ -149,7 +149,7 @@ def add_atomic_sets(sets)
149149
# @example Perform a batch $set.
150150
# batchable.execute_batch_set(docs)
151151
#
152-
# @param [ Array<Document> ] docs The docs to persist.
152+
# @param [ Array<Mongoid::Document> ] docs The docs to persist.
153153
#
154154
# @return [ Array<Hash> ] The inserts.
155155
def execute_batch_set(docs)
@@ -172,7 +172,7 @@ def execute_batch_set(docs)
172172
# @example Perform a batch push.
173173
# batchable.execute_batch_push(docs)
174174
#
175-
# @param [ Array<Document> ] docs The docs to persist.
175+
# @param [ Array<Mongoid::Document> ] docs The docs to persist.
176176
#
177177
# @return [ Array<Hash> ] The inserts.
178178
def execute_batch_push(docs)
@@ -234,9 +234,9 @@ def inserts_valid=(value)
234234
# @example Normalize the docs.
235235
# batchable.normalize_docs(docs)
236236
#
237-
# @param [ Array<Document> | Array<Hash> ] docs The docs to normalize.
237+
# @param [ Array<Mongoid::Document> | Array<Hash> ] docs The docs to normalize.
238238
#
239-
# @return [ Array<Document> ] The docs.
239+
# @return [ Array<Mongoid::Document> ] The docs.
240240
def normalize_docs(docs)
241241
if docs.first.is_a?(::Hash)
242242
docs.map do |doc|
@@ -309,7 +309,7 @@ def selector
309309
# @example Pre process the documents.
310310
# batchable.pre_process_batch_insert(docs)
311311
#
312-
# @param [ Array<Document> ] docs The documents.
312+
# @param [ Array<Mongoid::Document> ] docs The documents.
313313
#
314314
# @return [ Array<Hash> ] The documents as an array of hashes.
315315
def pre_process_batch_insert(docs)
@@ -335,7 +335,7 @@ def pre_process_batch_insert(docs)
335335
# @example Pre process the documents.
336336
# batchable.pre_process_batch_remove(docs, :delete)
337337
#
338-
# @param [ Array<Document> ] docs The documents.
338+
# @param [ Array<Mongoid::Document> ] docs The documents.
339339
# @param [ Symbol ] method Delete or destroy.
340340
#
341341
# @return [ Array<Hash> ] The documents as hashes.
@@ -362,7 +362,7 @@ def pre_process_batch_remove(docs, method)
362362
# @example Post process the documents.
363363
# batchable.post_process_batch_insert(docs)
364364
#
365-
# @param [ Array<Documents> ] docs The inserted docs.
365+
# @param [ Array<Mongoid::Document> ] docs The inserted docs.
366366
#
367367
# @return [ Enumerable ] The document enum.
368368
def post_process_batch_insert(docs)
@@ -380,10 +380,10 @@ def post_process_batch_insert(docs)
380380
# @example Post process the documents.
381381
# batchable.post_process_batch_remove(docs, :delete)
382382
#
383-
# @param [ Array<Document> ] docs The documents.
383+
# @param [ Array<Mongoid::Document> ] docs The documents.
384384
# @param [ Symbol ] method Delete or destroy.
385385
#
386-
# @return [ Array<Document> ] The documents.
386+
# @return [ Array<Mongoid::Document> ] The documents.
387387
def post_process_batch_remove(docs, method)
388388
docs.each do |doc|
389389
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
@@ -58,7 +58,7 @@ def unbind_one
5858
# @example Check for inverses errors.
5959
# binding.check_inverses!(doc)
6060
#
61-
# @param [ Document ] doc The document to check.
61+
# @param [ Mongoid::Document ] doc The document to check.
6262
def check_polymorphic_inverses!(doc)
6363
if inverses = _association.inverses(doc)
6464
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
@@ -16,14 +16,14 @@ module Buildable
1616
# @example Build the document.
1717
# Builder.new(meta, attrs).build
1818
#
19-
# @param [ Document ] base The object.
20-
# @param [ Document | Hash ] object The parent hash or document.
19+
# @param [ Mongoid::Document ] base The object.
20+
# @param [ Mongoid::Document | Hash ] object The parent hash or document.
2121
# @param [ String ] type Not used in this context.
2222
# @param [ Hash ] selected_fields Fields which were retrieved via
2323
# #only. If selected_fields are specified, fields not listed in it
2424
# will not be accessible in the built document.
2525
#
26-
# @return [ Document ] A single document.
26+
# @return [ Mongoid::Document ] A single document.
2727
def build(base, object, type = nil, selected_fields = nil)
2828
return object unless object.is_a?(Hash)
2929
if _loading?

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ class Proxy < Association::One
1616
# @example Create the new association.
1717
# Association::Embedded::EmbeddedIn.new(person, address, association)
1818
#
19-
# @param [ Document ] base The document the association hangs off of.
20-
# @param [ Document ] target The target (parent) of the association.
19+
# @param [ Mongoid::Document ] base The document the association hangs off of.
20+
# @param [ Mongoid::Document ] target The target (parent) of the association.
2121
# @param [ Mongoid::Association::Relatable ] association The association metadata.
2222
#
2323
# @return [ In ] The proxy.
@@ -34,9 +34,9 @@ def initialize(base, target, association)
3434
# @example Substitute the new document.
3535
# person.name.substitute(new_name)
3636
#
37-
# @param [ Document | Hash ] replacement A document to replace the target.
37+
# @param [ Mongoid::Document | Hash ] replacement A document to replace the target.
3838
#
39-
# @return [ Document | nil ] The association or nil.
39+
# @return [ Mongoid::Document | nil ] The association or nil.
4040
def substitute(replacement)
4141
unbind_one
4242
unless replacement
@@ -67,7 +67,7 @@ def binding
6767
# @example Set the base association.
6868
# object.characterize_one(document)
6969
#
70-
# @param [ Document ] document The document to set the association metadata on.
70+
# @param [ Mongoid::Document ] document The document to set the association metadata on.
7171
def characterize_one(document)
7272
_base._association ||= _association.inverse_association(document)
7373
end
@@ -112,7 +112,7 @@ def embedded?
112112
# @example Get the path calculator.
113113
# Proxy.path(document)
114114
#
115-
# @param [ Document ] document The document to calculate on.
115+
# @param [ Mongoid::Document ] document The document to calculate on.
116116
#
117117
# @return [ Root ] The root atomic path calculator.
118118
def path(document)

0 commit comments

Comments
 (0)