Libretro/RetroArch Documentation Project

General Development
#21

Hey guys.

I’m trying to help leiradel to document the cheevos.c, but I would like to know if there’s some preference for commenting style.

When I implemented the fill_str_dated_filename() function in file_path.c I used the comment style I found in the same file (as you can see here and on the snippet below).


/**
 * fill_str_dated_filename:
 * @out_filename       : output filename
 * @in_str             : input string
 * @ext                : extension of output filename
 * @size               : buffer size of output filename
 *
 * Creates a 'dated' filename prefixed by the string @in_str, and
 * concatenates extension (@ext) to it.
 *
 * E.g.:
 * out_filename = "RetroArch-{year}{month}{day}-{Hour}{Minute}{Second}.{@ext}"
 **/
void fill_str_dated_filename(char *out_filename,
      const char *in_str, const char *ext, size_t size)
{
   ...

But I noticed that this isn’t used in other parts of RetroArch code.

Then, I have some questions about the RetroArch commenting style:

  • Is there some tool to autogenerate docs when the comments are written using the style shown above?

  • Is there some coding style guide for the libretro/RetroArch?

Cheers!

#22

I talked to Twinaphex about it and he said the comment style you’re using in your post is just fine. We don’t have any automatic doc generation, so if you need to change the style to suit doxygen or whatever, post an example and I’ll run it by him.

#24

hunterk, doxygen seems to be the most widely used for documenting C code. But it’s a pain to get a nice Doxyfile configuration to output neat html docs specific for C language.

I tested it and it seems that Doxygen didn’t like the several #defines present in RetroArch code (as I said in the second question of doxygen FAQ).

I think I’ll go with the javadoc style. I know doxygen can manage this as input, I just need to find out how to get a nice Doxyfile configuration.

Look if the style is OK on the example below:


/**
 * Gets the list of awarded achievements for the game_id and updates
 * internal data accordingly.
 *
 * @param game_id : game ID.
 * @param timeout : max time, in microseconds, to get response from the server.
 * 
 * 
 * @return -1 on failure, JSONSAX_OK on success.
 */
static int cheevos_deactivate_unlocks(unsigned game_id, retro_time_t *timeout)
{
   ...

Thanks.

#25

Ok, so… Is there a TO-DO list or a Tree of Contents, to check what’s left?

I want to contribute by puting the ‘Core Software Library’ (aka the status of every core) section into the new mkdocs format.

Do I have to contact anyone in particular, or do I just push my stuff?

thx

#26

Just fork the repo, make your changes and then submit a PR. :slight_smile:

#27

I’m finding may way around now.

Does this mean the Android Compilation is outdated and not worth trying to follow just yet or just not ported to docs?

#28

I think this one is still valid:

#29

Thanks, I wasn’t sure as I found a couple.

i have no experience with this sort of thing so am totally confused if I need to use Android Studio and setup a new project or just get the environment install as per the guide.

Given up on it tonight but will have another crack over the weekend

#31

Wow,

for me this is like entering the Matrix! I am not sure whats happening but things are moving forward.

#32

First generation cores, as Telejogo, Telejogo II, Videorama, TV Jogo 3, TV Jogo 4, Nintendo Color TV Game, Atari Pong, Magnavox Odyssey and Coleco Telstar, are there on Retroarch?

#33

I don’t think there are dedicated cores for these systems, but if MAME supports them, you should be able to play them through the mame-libretro core.