[Docs] Populate's behavior is not greatly documented

[hasezoey]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

Currently populate's behavior is not greatly documented for cases in which it fails, the documentation currently just says not populated, which could mean many things, so this issue proposes that the documentation would need to be updated.

Current docs:

mongoose/lib/document.js

Lines 4181 to 4200 in 115f922

	/**
	* Populates paths on an existing document.
	*
	* #### Example:
	*
	* await doc.populate([
	* 'stories',
	* { path: 'fans', sort: { name: -1 } }
	* ]);
	* doc.populated('stories'); // Array of ObjectIds
	* doc.stories[0].title; // 'Casino Royale'
	* doc.populated('fans'); // Array of ObjectIds
	*
	* await doc.populate('fans', '-email');
	* doc.fans[0].email // not populated
	*
	* await doc.populate('author fans', '-email');
	* doc.author.email // not populated
	* doc.fans[0].email // not populated
	*

Things that should be changed / documented:

• change not populated to actually say what type is expected in case it fails (like is it null | undefined, or the raw id)
• what happens for paths that dont actually exist (does populate throw or try to do it anyway or just ignore it)
• document what the actual return type of .populate call is (currently it is just Promise)
• document that Document.prototype.populate is (at least a bit) different from Query.prototype.populate

PS: some of those may be fixed by just using the @see tags from the jsdoc in the documentation