Inline documentation updates

[mbaudis]

re-writing of some inline schema descriptions

This PR re-writes some of the root descriptions of the response type schemas (mostly) into slightly more verbose and formatted texts. Besides the "documentation is good" paradigm one reason is the intended use of these for generating documentation pages - see the (under construction) rendering at https://bycon.progenetix.org/generated/beacon-responses/

[mbaudis]

Hi @jrambla and @costero-e - can you please have a look if there are any factual errors? Otherwise this should be fast paced into main - only inline documentation changes.

Note: I've done this also for having a single point of documentation texts and w/ some maturity we can co-opt this for docs.genomebeacons.org later on. See https://bycon.progenetix.org/API/

(updated with the canonical https://bycon.progenetix.org/API/ link)

[costero-e]

Hi @mbaudis. I'm afraid this will conflict with the work in #174, that we are merging into clean-up. Either we wait until that is merged before or we work in the same PR. On the other hand, I see that we are only adding these modifications for .yml files but not for .json files, is there a specific reason for that? Thank you!

[mbaudis]

@costero-e Hmmm... Why would this conflict with #174 ? Beyond rebasing etc. things, potentially. And yes, I did not run the JSON converter before committing; added now.

[costero-e]

I was thinking in entryTypeDefinition.json file, which in #174 we are removing the filteringTerms entry and here is still existing. A same file modified by two different commits that are unaligned will make git complain I think.