TL;DR: Use the "TRANSLATORS" tag for marking the comments for translators.
Currently we extract *all* preceding comments to the generated POT files. The side effect is that in some cases the comment contains the license header, Yardoc comments or even commented out code. That might be confusing for translators.
The solution is to use some special tag and instruct gettext to extract the comments only following this special tag. We already use the "TRANSLATORS" tag in YaST for that.
# this comment is *not* copied to the POT file # TRANSLATORS: this comment *is* copied to the POT file # this *is* copied as well _("Translatable text")
Unfortunately it is not used everywhere, when I tried to use it globally a lot of comments from POT files were lost.
For that reason I have introduced the POTCOMMENTS file, similar to the existing POTFILES used in some repositories. That file should contain the tag name passed to gettext. I.e. it should just contain the "TRANSLATORS" value so it is the same in all repositories.
If that file is missing the old approach (all comments) is used, so it is backward compatible and we can gradually fix the modules one by one.