Add Doxygen-styled comments to parts of the libretro API

[JesseTG]

Description

This pull request will add Doxygen-styled comments to various parts of the libretro API to simplify their use. Even if HTML pages are not generated or hosted, Doxygen is common enough that IDEs will recognize it. Here's what it looks like in CLion:

The comments are written to adhere to SemBr for easier diffs and clearer sentence structure. Essentially, line breaks are treated like punctuation.

This PR will not:

• Violate C90. All additions come as /** standard C90 comments */.
• Change how types, functions, macros, etc. are declared.
• Generate documentation pages. This just adds comments.
• Document RetroArch internals. This is for the benefit of libretro-common.

This PR, as of this writing, is only a sample. If @LibretroAdmin approves the general style, then I will proceed to document the rest of <libretro.h> (plus some other libretro-common APIs I've used) in the same format.

Reviewers

@LibretroAdmin @RobLoach

Status

The goal of this PR is to document all public-facing the parts of libretro-common that I've used. Here's where that stands:

• array
  • rbuf.h
  • rhmap.h
• audio
  • audio_mix.h
  • audio_mixer.h
  • audio_resampler.h
  • conversion
    • dual_mono.h
    • float_to_s16.h
    • s16_to_float.h
  • dsp_filter.h
• boolean.h
• cdrom/cdrom.h
• clamping.h
• compat No need to write bespoke documentation for every single compatibility symbol, but libretro-specific limitations do need to be pointed out. It's enough to link to the documentation pages for whatever functions these reimplement.
  • apple_compat.h
  • fnmatch.h
  • fopen_utf8.h
  • getopt.h
  • ifaddrs.h
  • intrinsics.h
  • msvc/stdint.h
  • msvc.h
  • posix_string.h
  • strcasestr.h
  • strl.h
  • zlib
    • zconf.h
    • zlib.h
• defines Same deal here, just link to the documentation pages that acutally describe these.
  • cocoa_defines.h
  • d3d_defines.h
  • gx_defines.h
  • ps3_defines.h
  • ps4_defines.h
  • psp_defines.h
• dynamic/dylib.h
• encodings
  • base64.h
  • crc32.h
  • utf.h
  • win32.h
• fastcpy.h
• features/features_cpu.h
• file
  • archive_file.h
  • config_file.h
  • config_file_userdata.h
  • file_path.h
  • nbio.h
• filters.h
• formats
  • cdfs.h
  • image.h
  • logiqx_dat.h
  • m3u_file.h
  • rbmp.h
  • rjpeg.h
  • rjson.h
  • rjson_helpers.h
  • rpng.h
  • rtga.h
  • rwav.h
  • rxml.h
• gfx
  • gl_capabilities.h
  • math
    • matrix_3x3.h
    • matrix_4x4.h
    • vector_2.h
    • vector_3.h
    • vector_4.h
  • scaler
    • filter.h
    • pixconv.h
    • scaler.h
    • scaler_int.h
  • video_frame.h
• glsym
  • glsym.h
  • glsym_es2.h
  • glsym_es3.h
  • glsym_gl.h
  • rglgen.h
  • rglgen_headers.h
  • rglgen_private_headers.h
  • switch
    • nx_gl.h
    • nx_glsym.h
• libchdr
  • bitstream.h
  • cdrom.h
  • chd.h
  • coretypes.h
  • flac.h
  • huffman.h
  • libchdr_zlib.h
  • lzma.h
  • minmax.h
• libco.h
• libretro.h This is the big one. Partly done, not complete.
• libretro_d3d.h
• libretro_dspfilter.h
• libretro_gskit_ps2.h
• libretro_vulkan.h
• lists
  • dir_list.h
  • file_list.h
  • linked_list.h
  • nested_list.h
  • string_list.h
• lrc_hash.h
• math
  • complex.h
  • float_minmax.h
  • fxp.h
• media/media_detect_cd.h
• memalign.h
• memmap.h
• net
  • net_compat.h
  • net_http.h
  • net_http_parse.h
  • net_ifinfo.h
  • net_socket.h
  • net_socket_ssl.h
• playlists/label_sanitization.h
• queues
  • fifo_queue.h
  • generic_queue.h
  • message_queue.h
  • task_queue.h
• retro_assert.h
• retro_common.h
• retro_common_api.h
• retro_dirent.h
• retro_endianness.h
• retro_environment.h
• retro_inline.h
• retro_math.h
• retro_miscellaneous.h
• retro_timers.h
• rthreads
  • async_job.h This has no definitions or users; I'm pretty sure this is obsolete functionality that was removed.
  • rthreads.h
  • tpool.h
• streams
  • chd_stream.h
  • file_stream.h
  • file_stream_transforms.h
  • interface_stream.h
  • memory_stream.h
  • network_stream.h
  • rzip_stream.h
  • stdin_stream.h
  • trans_stream.h
• string/stdstring.h
• time/rtime.h
• utils/md5.h
• vfs
  • vfs.h
  • vfs_implementation.h
  • vfs_implementation_cdrom.h
• vulkan/vulkan_symbol_wrapper.h

[RobLoach]

I've been wanting doxygen in here FOREVER. Happy to help out on its transition, if the rest of the libretro team are 👍

[JesseTG]

I've been wanting doxygen in here FOREVER. Happy to help out on its transition, if the rest of the libretro team are 👍

Great! How do you wanna divvy up the work? I'm happy to flesh out the docs for the environment calls plus any APIs that I've used so far. (That includes the VFS, task queue, and image scaler.) I'm also happy to proofread for spelling and clarity.

The APIs I've contributed already use Doxygen comments.

[JesseTG]

I'm still working on this. I've been prioritizing melonDS DS, but I've been squeezing in some work here whenever I'm blocked on something. I've finished with most parts of libretro.h. Once I complete it (and one other header whose changes I haven't pushed yet), I'll go around requesting reviews.

[JesseTG]

In the interest of not letting this languish while I move on to something else, I've decided to call this branch done. Any gaps in it will be filled in future PRs. In the meantime, could I get some eyes on the contents?

[XerTheSquirrel]

I know I am not a originally requested reviewer, but I took a look at this and reviewed. I really do like the work that was done despite it being incomplete, I do agree that it should get merged in sooner so there is no gigantic feature creep kind of thing. This will also make development through IDEs must easier as well. I did not see any glancing issues at all as most of the documentation is just a transfer over and more clarification, which was fine for me.

The conflicts do need to be resolved before a final merge however.

[RobLoach]

@LibretroAdmin I believe this is good to go. Had another look through and there isn't any API or function definition that is changing, it's all documentation. Expanding to the rest of libretro-common could likely happen after this is merged in. Touching the majority of libretro.h is an incredible accomplishment here 👍

I don't see any conflicts on merging. Perhaps rather than a merge, a Squash and Merge would be better to ease the git history.

[JesseTG]

@LibretroAdmin I believe this is good to go. Had another look through and there isn't any API or function definition that is changing, it's all documentation.

One exception; I do add a new enum here for RETRO_ENVIRONMENT_GET_AUDIO_VIDEO_ENABLE. However, the size and range of the enum's values are consistent with the hardcoded numbers in the original documentation, so I don't foresee any ABI problems.

[RobLoach]

This is looking really solid. While there could be nitpick improvements to both the docs, and the formats, we could take those on as follow ups. Being able to read the docs directly in your IDE is nice, and it does pave the way to generating API docs automagically for libretro too...

I'd recommend merging this up, and then taking on individual parts of libretro-common as follow ups.

[LibretroAdmin]

@Jamiras can still review it.

[RobLoach]

Sounds good with me. The more eyes we have on this the better. When we decide to merge this forwards, it may be best to "Squash and merge" so that the git history doesn't get too crazy.