Fix return value of Fl_Table_Row::row_selected(int) (PR #1187)

As discussed in the context of PR #1187 the previous return value '-1'
was misleading and undocumented. The docs mentioned only '1' and '0'.

User code that used the return value as documented (like a `bool`)
would make the wrong decision if the return value was '-1': true
(selected) instead false (out of range).

This commit fixes the code by doing what the docs define and clarifies
the documentation.

Further documentation improvements of Fl_Table (example code used a
method that is not defined in Fl_Table) and of Fl_Table_Row are
included as well.

Doxygen docs of two methods of Fl_Table_Row moved to the .cxx file
where they belong according to the CMP.