HfstTransducer.n_best() documentation misleading

[maciejjan]

The documentation of HfstTransducer.n_best(), both in Python and in C++ API, says that the method "extracts paths" and "returns paths", which suggests a behaviour analogous to HfstTransducer.extract_paths(), HfstTransducer.extract_shortest_paths() etc., but returning the n best paths.

In reality, the method modifies the supplied transducer to contain only the n best paths. In the Python API, it does not return anything.

>>> a = hfst.fst(('foo', 3.0)) 
>>> a.disjunct(hfst.fst(('bar', 5.0))) 
>>> a.extract_paths() 
{'foo': [('foo', 3.0)], '@_EPSILON_SYMBOL_@bar': [('@_EPSILON_SYMBOL_@bar', 5.0)]} 
>>> b = a.n_best(1) 
>>> b 
>>> b is None 
True 
>>> a.extract_paths() 
{'foo': [('foo', 3.0)]} 

(version: 3.15.0 under Debian)