Removing NodeNG.nearest method

[kavins14]

EDIT:
Based on discussions below we have decided to remove this method altogether because it's not being used in astroid or pylint and that it doesn't seem to have any use in the near future.

Steps to reproduce

Run this script:

src = """
print(before)
print(random)
print(middle)
print(after)
"""
mod = astroid.parse(src)
before, _, middle, after = mod.body
print(middle.nearest([before, after]))

Current behavior

middle.nearest([before, after]) returns before.

Expected behavior

middle.nearest([before, after]) should return after since it's closer

Issue Description

The issue is that for a NodeNG node n, n.nearest method only returns the nearest node that occurs on lines before n and disregards any nodes on the lines after.

https://github.com/PyCQA/astroid/blob/33488e28677a1e980361757cdb1db0eb13c99435/astroid/node_classes.py#L582-L607

I see two possible fixes for this:

1. Fix the method implementation so that the node that is the closest (either before or after) is returned (where precedence is given to the node before).
2. Update the docstring so that it is in tandem with how the method currently works.

I think that fix (1) is in line with method description so I will be making a PR for this.

Note: There is no usage of NodeNG.nearest in both pylint's and astroid's source code.

python -c "from astroid import __pkginfo__; print(__pkginfo__.version)" output

2.3.0

[PCManticore]

Thanks @kavins14 Makes sense to fix this, but I wonder if it's not better to remove this method altogether. Someone might use it in a pylint / astroid plugin, but we can emit a deprecation warning for the next release, followed by completely removing it in a prior release.

[kavins14]

By defining nearest as the closest node by line number, the method is essentially comparing nodes based on how the source code is written. Other than for style-related checkers this method doesn't seem to be too useful. Maybe this is why it is not used at all in pylint and astroid.
I think it would make sense to remove this method altogether. Should I create a new issue/pr to do that?

[PCManticore]

Sounds good, we can reuse the current issue and PR for the same effect.