Improve yardoc tags for better documentation

[ekohl]

When using yardoc server to serve the documentation, the Foreman namespace was incorrectly documented. This makes sure some files are readable. Obviously it's far from ready.

This came up in a discussion about developer docs: https://community.theforeman.org/t/rfc-improve-developer-documentation-and-learning-resources/38167.