Kodi Community Forum
Proposed Jenkins test to detect (some) corrupt documentation - Printable Version

+- Kodi Community Forum (https://forum.kodi.tv)
+-- Forum: Development (https://forum.kodi.tv/forumdisplay.php?fid=32)
+--- Forum: Kodi Application (https://forum.kodi.tv/forumdisplay.php?fid=93)
+--- Thread: Proposed Jenkins test to detect (some) corrupt documentation (/showthread.php?tid=377476)

Proposed Jenkins test to detect (some) corrupt documentation - DeltaMikeCharlie - 2024-05-10

Excuse me if this has been proposed before.

I assume that it is well known that when the Doxygen tags contain syntax errors, the resulting documentation can be malformed (I have been responsible for this on more than 1 occasion).  I have noticed that this malformation usually manifests as Doxygen tags being visible in the final HTML code.

Image

I’d like to suggest that part of the PR pre-flight processes on GitHub includes building the documentation and then running a simple:

Code:
grep -r -i "\\\table_row"|wc -l

If the result is not equal to zero, then the documentation may need to be reviewed manually.

Something like this:

Code:
grep -r -i "\\\table_row"|awk '{print $1}'

Can identify the HTML file name, but not the source code from which it originated.

I’m sure that malformed documentation can result from other Doxygen syntax errors and as they are discovered they could be added to the test.

RE: Proposed Jenkins test to detect (some) corrupt documentation - DeltaMikeCharlie - 2024-05-11

I’m sure that there is considerable room for refinement here, however, this:

Code:
grep -r -i "\\\table_row" .|gawk -F"<code>" '{print $2}'|gawk -F"</code>" '{print $1}'

Turned this:

Code:
./d0/d3e/page__list_of_built_in_functions.html:    <tr><td class="paramdir">[in]</td><td class="paramname">param</td><td>"restart" to restart from resume point (optional)  \table_row2_l{ <b><code>PlayerControl(control[\,param])</code></b> , Allows control of music and videos. <br  />

./d0/d3e/page__list_of_built_in_functions.html:    <tr><td class="paramdir">[in]</td><td class="paramname">position</td><td>Position in playlist if params[0] is playlist type (optional).  \table_row2_l{ <b><code>PlayMedia(media[\,isdir][\,1]\,[playoffset=xx])</code></b> , Plays the given media. This can be a playlist\, music\, or video file\, directory\, plugin\, disc image stack\, video file stack or an URL. The optional parameter <code>,isdir</code> can be used for playing a directory. <code>,1</code> will start the media without switching to fullscreen. If media is a playlist or a disc image stack or a video file stack\, you can use playoffset=xx where xx is the position to start playback from. </td></tr>

./d0/d3e/page__list_of_built_in_functions.html:    <tr><td class="paramdir">[in]</td><td class="paramname">seconds</td><td>Number of seconds to seek.  \table_row2_l{ <b><code>QueueMedia(media[\,isdir][\,1][\,playnext]\,[playoffset=xx])</code></b> <a class="anchor" id="Builtin_QueueMedia"></a>, Queues the given media. This can be a playlist\, music\, or video file\, directory\, plugin\, disc image stack\, video file stack or an URL. The optional parameter <code>,isdir</code> can be used for playing a directory. <code>,1</code> will start the media without switching to fullscreen. If media is a playlist or a disc image stack or a video file stack\, you can use playoffset=xx where xx is the position to start playback from. where xx is the position to start playback from. </td></tr>

./d5/d11/modules__infolabels_boolean_conditions.html:<p class="intertd"> </td></tr> \table_row3{ <b><code>VideoPlayer.VideoVersionName</code></b>, <a class="anchor" id="VideoPlayer_VideoVersionName"></a> <em>string</em>, </p><dl class="section return"><dt>Returns</dt><dd>String containing the version name of the currently playing video (movie) - empty if not a movie, version name is not set or not a version </dd></dl>

./d5/d11/modules__infolabels_boolean_conditions.html:<p class="intertd"> </td></tr> \table_row3{ <b><code>ListItem.AlbumStatus</code></b>, <a class="anchor" id="ListItem_AlbumStatus"></a> <em>string</em>, </p><dl class="section return"><dt>Returns</dt><dd>The Musicbrainz release status of the album (official, bootleg, promotion etc) </dd></dl>

Into this:

Code:
PlayerControl(control[\,param])
PlayMedia(media[\,isdir][\,1]\,[playoffset=xx])
QueueMedia(media[\,isdir][\,1][\,playnext]\,[playoffset=xx])
VideoPlayer.VideoVersionName
ListItem.AlbumStatus

It may not give the exact source file name and location, but it gives a good hint regarding the general proximity in which to start looking.

The results could be added to a GitHub comment with a suggestion that the PR owner review their code.

RE: Proposed Jenkins test to detect (some) corrupt documentation - DeltaMikeCharlie - 2024-05-12

(2024-05-11, 06:17)DeltaMikeCharlie Wrote:
Code:
PlayerControl(control[\,param])
PlayMedia(media[\,isdir][\,1]\,[playoffset=xx])
QueueMedia(media[\,isdir][\,1][\,playnext]\,[playoffset=xx])
VideoPlayer.VideoVersionName
ListItem.AlbumStatus

Taking the output of the previous post, it should also be possible to search the DIFF of the PR for a match, failing that, entire source tree could also be searched. This could help identify the source file involved.