search

libsdl-org / SDL_mixer

An audio mixer that supports various file formats for Simple Directmedia Layer.
zlib License
432 stars 147 forks source link

wikiheaders: don't warn about missing files by default #552

Closed madebr closed 1 year ago

madebr commented 1 year ago

https://github.com/libsdl-org/SDL_mixer/issues/542

wikiheaders.pl has --warn-about-missing to force the value to 0.

@icculus Is this ok? Or is a --no-warn-about-missing option preferred?

slouken commented 1 year ago

Suggest removing "about", e.g. --warn-missing or --warn-missing-files

madebr commented 1 year ago

Suggest removing "about", e.g. --warn-missing or --warn-missing-files

That's up to @icculus. In a sense, the option is private, and meant for project maintainers only.

icculus commented 1 year ago

Let's either fix the missing things or change the default in the script itself.

madebr commented 1 year ago

Let's either fix the missing things or change the default in the script itself.

The warning is emitted when a function is documented in the wiki but not in the headers (and the reverse case) This warning makes sense when generating the wiki at https://wiki.libsdl.org, but does not when generating the man pages. (the perl script cannot generate man pages without the wiki pages present)

icculus commented 1 year ago

Really it doesn't make sense when generating wiki.libsdl.org either, because the cronjob just sends it to me in an email where I ignore it. :)

What if, instead of printing warnings, it generates a wiki page called "Undocumented.md" that updates on each run? That way we would have a public list of things that lack documentation.

icculus commented 1 year ago

For now, though, let's just change the default in the script.

madebr commented 1 year ago

For now, though, let's just change the default in the script.

The default is fine:

https://github.com/libsdl-org/SDL_mixer/blob/3cb07a1f4b6fa02b83298c025f2994cc770cbcf0/build-scripts/wikiheaders.pl#L28

It's the project-specific configuration that has the override:

https://github.com/libsdl-org/SDL_mixer/blob/3cb07a1f4b6fa02b83298c025f2994cc770cbcf0/.wikiheaders-options#L15

SDL has it disabled

icculus commented 1 year ago

Oh. Ok then. :)

madebr commented 1 year ago

What if, instead of printing warnings, it generates a wiki page called "Undocumented.md" that updates on each run? That way we would have a public list of things that lack documentation.

Great idea. About wikiheaders.pl, in case you missed it, I pushed this patch yesterday: https://github.com/libsdl-org/SDL/commit/e85206ffd8becd33321182614e2ba5a5d304a5a3