Missing compiler flag documentation

[kavika13]

I searched for all defined and ifdef flag checks and created a list.

I scrubbed the list to remove:

• flags that are documented on the website.
• flags I know are compiler/target provided.
• flags that are defined inside the header itself (which are presumably are mostly used for internal logic, and probably should only be provided externally as a workaround).

Here's a list of the remaining flags that seem to be invented by this project (or a dependency), but aren't documented.

I assume some of them are intentionally undocumented, though maybe that should be reconsidered.
(e.g. MA_DLL is unsupported, but is still a flag that would be provided externally if the user chooses to use it anyway. Documenting it in the list of known flags I think could still be useful, and just repeat the "not supported" comment there)

Some of them may also be vestigial and could be removed (e.g. I think MA_HAS_OPUS might be in that category).

Here's the list:

• MA_DLL
• MA_DR_FLAC_IMPLEMENT_CLZ_WATCOM_LZCNT
• MA_DR_FLAC_IMPLEMENTATION
• MA_DR_FLAC_NO_CRC
• MA_DR_FLAC_NO_NEON
• MA_DR_FLAC_NO_SIMD
• MA_DR_FLAC_NO_SSE2
• MA_DR_FLAC_NO_SSE41
• MA_DR_MP3_FLOAT_OUTPUT
• MA_DR_MP3_IMPLEMENTATION
• MA_DR_MP3_ONLY_MP3
• MA_DR_WAV_IMPLEMENTATION
• MA_DR_WAV_LIBSNDFILE_COMPAT
• MA_ENABLE_CUSTOM
• MA_FORCE_UWP
• MA_HAS_OPUS
• MA_NO_CUSTOM
• MA_NO_VORBIS
• MA_NO_WIN32_FILEIO
• MA_ON_THREAD_ENTRY
• MA_ON_THREAD_EXIT
• MA_STATIC
• MA_THREAD_DEFAULT_STACK_SIZE
• MA_USE_REFERENCE_CONVERSION_APIS
• MA_USE_STDINT
• STB_VORBIS_INCLUDE_STB_VORBIS_H

If you like this approach and choose to keep this bug open, feel free to utilize the checklist and modify the issue as you see fit.

[kavika13]

This search was done on the main branch. I didn't check which of them were addressed in the dev branch.
I could redo the search on the dev branch (and potentially diff them) if that would be useful.

[mackron]

Thanks. There's a few on here I'm intentionally leaving undocumented because I don't want to encourage them. The following I have no interest in documenting:

MA_DLL: miniaudio does not have a stable API or ABI so I don't want to encourage compiling as a DLL. This is a backdoor for people with specific requirements.

MA_DR_*: These ones are pulled in from an amalgamation process and should be considered an implementation detail.

STB_VORBIS_INCLUDE_STB_VORBIS_H and MA_NO_VORBIS: These are a historical artefact and exist for some backwards compatibility that will be removed in a future version of miniaudio.

MA_NO_WIN32_FILEIO and MA_USE_REFERENCE_CONVERSION_APIS: These are for debugging.

The others I'll need to look at. Like you said some can definitely be removed, including MA_HAS_OPUS.

[kavika13]

Maybe these warrent separate tickets:

Would it make sense to use some sort of naming convention to distinguish between supported and other defines? Maybe could be one for public, one for unsupported, and one for private. Then it would become easy to verify what should and shouldn't be documented.

And is the amalgamated DR header documented elsewhere, and if so, is there a link to it in the docs already? If so, then I agree that's covered. If not, then maybe that warrants a separate ticket as well.