Doxygen documentation about gsl

[dmitrykobets-msft]

maintainers' call:
let's check-in the documentation into the repo as markdown files under some documentation folder structure (i.e., docs/). This will require edits to be reviewed in a PR. These docs should be linked to from the README.
Your suggestions of "header files, classes, public members, global functions and public methods" are all good candidates.

I'll add a skeleton structure for the docs. This is not set in stone, so feel free to make improvements if you see fit.

[dmitrykobets-msft]

Hi @beinhaerter,
Thanks for volunteering to do this! I'll gather thoughts about Doxygen at the next maintainers' sync.

[dmitrykobets-msft]

Hi @beinhaerter,
We would prefer to have the documentation reside in the wiki, which would use GFM. If there exists a way to incorporate Doxygen into this for ease-of-use (i.e., prevent divergence between source-code and documentation) that could potentially be useful.

[beinhaerter]

My goal is to put a current GSL repo snapshot together with the matching docs so that both are always in sync and can be published in one step.

I like the Doxygen approach to put the documentation into the sources. That easily keeps them in sync and is very good for describing the individual functions.

I like the markdown approach because that is good for describing overviews. Doxygen understands markdown files, but simple markdown and not the Github extensions. If the Github extensions are not used (or in not so many places), then both tools could use the same files, that would allow an easy dual use.

I don't see a way to get Doxygen to output the source annotations as markdown files. I found this opensource project doing a Doxygen HTML output to markdown conversion, but the last change in the repo was 6 years ago. I doubt that this is a good way to go (but I might give it a try if I have some spare time), so maybe the Wiki GFM way is a good way to go.

One thing I already noticed: the filename gsl::span-and-std::span.md blocks me from cloning the repo on Windows. Filenames with a colon are not valid filenames in Windows.

Currently most of the documentation is in README.md. And the Wiki is at least not presented very prominently. I am a contributor for some time but have never come across the Wiki. And even when opening https://github.com/microsoft/GSL/wiki there seems to be no content. The reader must look at the right side and understand that there are bulletins for the Wiki content. I think it would be better to have a start page that links to the sub pages. And probably add a Wiki link to the README.md (I know technically there is one, but that is hidden somewhere in the middle).

I you want others like me to add some content, then it would be helpful to

• give guidance what we want to document
  • the header files?
  • the classes (their name, their uses)?
  • public class members?
  • global functions and public class member functions?
• give a structure with some skeleton files that others could fill with more information
  • structure by header files?
  • structure by classes?
  • which paragraphs in which order do we want?
  • something like cppreference.com?

[beinhaerter]

@dmitrykobets-msft Thanks. I started adding some more docs in my branch https://github.com/beinhaerter/GSL/tree/add_docs.
Feel free to look at it in advance and to comment.
I see you made one headers.md file. I'll fill it over time, but I believe it will get too big so that it would be better to have some more files. But we can wait and see how it evolves.