net: pkt: Add API documentation for net_pkt_get_len

net_pkt_get_len() was commonly used yet not documented, move the
function out of the doxygen-ignored section of the header and add
a doxygen API description for the function so that it's rendered in
the documentation properly.

Signed-off-by: Robert Lubos <robert.lubos@nordicsemi.no>