Document Libdoc's public API better

[pekkaklarck]

Currently robot.libdoc API docs mention that libdoc and libdoc_cli functions are public and that everything else is private. robot.libdocpkg just tells that the whole package is private. We also have LibradyDocumentation factory method that external tools can use but it's not declared public. Enhancements to be done:

• Document that LibradyDocumentation is part of the public API.
• Recommend importing it via robot.libdoc. This also needs a test.
• Add documentation to LibradyDocumentation. Needs an example and reference to the returned LibraryDoc class.
• Add at least some documentation to LibraryDoc and KeywordDoc.
• Document that related DocumentationBuilder (see also Libdoc's DocumentationBuilder doesn't anymore work with resource files with .robot extension #4519) is not part of the public API.