fixed apidoc short description

fixes #2797
removed `@link` tags from apidoc and replaced with markdown