deprecate confusing Pkg.CandVersion() method

This method does not return the 'current' candidate of the DepCache
which would be most expected, but instead returns the version which
would be candidate in a default-only policy setting – aka ignoring
apt_preferences settings and co.

apt-pkg/cacheiterators.h

@@ -175,7 +175,7 @@ class pkgCache::PkgIterator: public Iterator<Package, PkgIterator> {
 	inline DepIterator RevDependsList() const APT_PURE;
 	inline PrvIterator ProvidesList() const APT_PURE;
 	OkState State() const APT_PURE;
-	const char *CandVersion() const APT_PURE;
+	APT_DEPRECATED_MSG("This method does not respect apt_preferences! Use pkgDepCache::GetCandidateVersion(Pkg)") const char *CandVersion() const APT_PURE;
 	const char *CurVersion() const APT_PURE;
 
 	//Nice printable representation

apt-pkg/cacheset.h

@@ -325,7 +325,7 @@ public:
 		inline pkgCache::DepIterator RevDependsList() const { return getType().RevDependsList(); }
 		inline pkgCache::PrvIterator ProvidesList() const { return getType().ProvidesList(); }
 		inline pkgCache::PkgIterator::OkState State() const { return getType().State(); }
-		inline const char *CandVersion() const { return getType().CandVersion(); }
+		APT_DEPRECATED_MSG("This method does not respect apt_preferences! Use pkgDepCache::GetCandidateVersion(Pkg)") inline const char *CandVersion() const { return getType().CandVersion(); }
 		inline const char *CurVersion() const { return getType().CurVersion(); }
 		inline pkgCache *Cache() const { return getType().Cache(); }
 		inline unsigned long Index() const {return getType().Index();}