Consider moving docs for SIMDe extensions inline, adding doxygen or similiar

[mr-c]

I just added stubs for the remaining SIMDe extensions to https://github.com/simd-everywhere/simde/wiki/Extensions and vast majority of them are out of date.

Wouldn't it be better to document the extensions within the code and use doxygen or similar to generate docs for the simde_x_* functions?

[nemequ]

It feels a bit odd to include doxygen comments for SIMDe extensions but not the normal functions.

A few options come to mind:

We could only document families (e.g., "xorsign" instead of simde_x_mm_xorsign_ps, simde_x_mm_xorsign_pd, simde_x_mm256_xorsign_ps, etc.).

We don't really have to document all of these functions; there are some extensions which are really only meant for internal usage, such as the lzcnt ones. And I think the GFNI ones, but maybe @rosbif has different opinion on that.

Another option would be to add doxygen comments for all functions. This is something I've been thinking about as a possibility for a while, but I'm really on the fence.

The main drawback (other than the fact that we would have to write it) is that it would significantly increase the size of the headers, which are already quite large. I don't think it would have much of an impact on compile time, though.

The main benefit is that it would allow IDEs to display more information. Also docs are more likely to be up to date (see this issue).

Now that AVX-512 is split up into one file per function family instead of one file per ISA extension I think this is a bit more plausible, though it will still be a bit rough for some of the larger earlier ISA extensions… Here are the current largest headers (and their size in lines):

  11948 ./x86/svml.h
   7089 ./x86/sse2.h
   6240 ./x86/avx.h
   5613 ./x86/avx2.h
   4303 ./x86/sse.h
   3101 ./arm/neon/reinterpret.h
   2280 ./x86/mmx.h
   2276 ./x86/avx512/cmp.h
   2145 ./x86/sse4.1.h
   1971 ./hedley.h
   1568 ./simde-math.h
   1065 ./x86/ssse3.h

Obviously Hedley wouldn't be included in this. simde-math.h is a bit of an edge case, I'm not sure if we should bother documenting it or not since it's really just libm wrappers.

[rosbif]

We don't really have to document all of these functions; there are some extensions which are really only meant for internal usage, such as the lzcnt ones. And I think the GFNI ones, but maybe @rosbif has different opinion on that.

(Sorry for the very late response.)

Yes, most of the GFNI ones are for local use to factor out code which is often complex and which would otherwise be repeated several times. They are too Galois Field specific to be useful for implementing intrinsics in other instruction subsets. Unless, of course, Intel introduces e.g. a GFNI2 instruction subset or AVX1024 ;-)