Better heuristic needed for property comments

[theunrepentantgeek]

Describe the current behavior

As of PR #1767, we select between multiple candidate property comments by selecting the longer one, assuming that it will be more specific (less generic).

This isn't an ideal solution, as it may sometimes choose a comment from a mixin instead of the one specified on the resource definition.

Describe the improvement

@Porges suggests that we should do the selection based on depth of the type in the recursive tree being walked.

Additional context

See also #1657 for the original bug report.

[matthchr]

This might actually be improved by #2084.

[matthchr]

Lets revisit this after we merge the Swagger PRs

[matthchr]

We need to double-check if we still need this issue.

[theunrepentantgeek]

Still need to double check

[matthchr]

In practice it seems that this is working well for us. Going to close this. If there is a user complaint about this we can revisit.