[FFmpeg-devel] [PATCH 0/3] Fix /// comments that should be ///<

[FFmpeg-devel] [PATCH 0/3] Fix /// comments that should be ///<

[Andrew Sayers]

This is the first in a planned series of patch series aimed at
fixing documentation issues, especially doxygen rendering.
I hope to post more as time allows in the coming days.

The first patch reflects the output of a `sed` command,
further patches fix edge cases not covered by `sed`.
Splitting commits this way allows merge conflicts
to be resolved by throwing the old commit away,
then running the command in the commit message.

Andrew Sayers (3):
      all: Fix /// comments that should be ///<
      avcodec/ivi: Make comments more Doxygen-friendly
      avcodec/avcodec: Downgrade multi-member comment to non-Doxygen comment

 libavcodec/avcodec.h     | 10 +++++-----
 libavcodec/bsf/noise.c   | 24 ++++++++++++------------
 libavcodec/ivi.h         | 15 +++++++--------
 libavfilter/vf_deshake.c |  2 +-
 libavformat/rmdec.c      |  4 ++--
 5 files changed, 27 insertions(+), 28 deletions(-)


_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

[FFmpeg-devel] [PATCH 1/3] all: Fix /// comments that should be ///<

[Andrew Sayers]

Actual command: sed -i -e "s/\([;,] *\)<* *\/\/\/ *<* */\1\/\/\/< /" $( git grep -l "[;,] */// " )

Signed-off-by: Andrew Sayers <ffmpeg-devel@pileofstuff.org>
---
 libavcodec/avcodec.h     |  8 ++++----
 libavcodec/bsf/noise.c   | 24 ++++++++++++------------
 libavcodec/ivi.h         | 10 +++++-----
 libavfilter/vf_deshake.c |  2 +-
 libavformat/rmdec.c      |  4 ++--
 5 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 43859251cc..58c581a5c0 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -1832,10 +1832,10 @@ typedef struct AVCodecContext {
      * - decoding: maintained and used by libavcodec, not intended to be used by user apps
      * - encoding: unused
      */
-    int64_t pts_correction_num_faulty_pts; /// Number of incorrect PTS values so far
-    int64_t pts_correction_num_faulty_dts; /// Number of incorrect DTS values so far
-    int64_t pts_correction_last_pts;       /// PTS of the last frame
-    int64_t pts_correction_last_dts;       /// DTS of the last frame
+    int64_t pts_correction_num_faulty_pts; ///< Number of incorrect PTS values so far
+    int64_t pts_correction_num_faulty_dts; ///< Number of incorrect DTS values so far
+    int64_t pts_correction_last_pts;       ///< PTS of the last frame
+    int64_t pts_correction_last_dts;       ///< DTS of the last frame
 
     /**
      * Character encoding of the input subtitles file.
diff --git a/libavcodec/bsf/noise.c b/libavcodec/bsf/noise.c
index 7bdaa3c1db..3a0f388dd6 100644
--- a/libavcodec/bsf/noise.c
+++ b/libavcodec/bsf/noise.c
@@ -28,18 +28,18 @@
 #include "libavutil/eval.h"
 
 static const char *const var_names[] = {
-    "n",                           /// packet index, starting from zero
-    "tb",                          /// timebase
-    "pts",                         /// packet presentation timestamp
-    "dts",                         /// packet decoding timestamp
-    "nopts",                       /// AV_NOPTS_VALUE
-    "startpts",                    /// first seen non-AV_NOPTS_VALUE packet timestamp
-    "startdts",                    /// first seen non-AV_NOPTS_VALUE packet timestamp
-    "duration", "d",               /// packet duration
-    "pos",                         /// original position of packet in its source
-    "size",                        /// packet size
-    "key" ,                        /// packet keyframe flag
-    "state",                       /// random-ish state
+    "n",                           ///< packet index, starting from zero
+    "tb",                          ///< timebase
+    "pts",                         ///< packet presentation timestamp
+    "dts",                         ///< packet decoding timestamp
+    "nopts",                       ///< AV_NOPTS_VALUE
+    "startpts",                    ///< first seen non-AV_NOPTS_VALUE packet timestamp
+    "startdts",                    ///< first seen non-AV_NOPTS_VALUE packet timestamp
+    "duration", "d",               ///< packet duration
+    "pos",                         ///< original position of packet in its source
+    "size",                        ///< packet size
+    "key" ,                        ///< packet keyframe flag
+    "state",                       ///< random-ish state
     NULL
 };
 
diff --git a/libavcodec/ivi.h b/libavcodec/ivi.h
index 06cd4d95ff..ec54f65f30 100644
--- a/libavcodec/ivi.h
+++ b/libavcodec/ivi.h
@@ -61,17 +61,17 @@ typedef struct IVIHuffDesc {
  *  macroblock/block huffman table descriptor
  */
 typedef struct IVIHuffTab {
-    int32_t     tab_sel;    /// index of one of the predefined tables
+    int32_t     tab_sel;    ///< index of one of the predefined tables
                             /// or "7" for custom one
-    VLC         *tab;       /// pointer to the table associated with tab_sel
+    VLC         *tab;       ///< pointer to the table associated with tab_sel
 
     /// the following are used only when tab_sel == 7
-    IVIHuffDesc cust_desc;  /// custom Huffman codebook descriptor
-    VLC         cust_tab;   /// vlc table for custom codebook
+    IVIHuffDesc cust_desc;  ///< custom Huffman codebook descriptor
+    VLC         cust_tab;   ///< vlc table for custom codebook
 } IVIHuffTab;
 
 enum {
-    IVI_MB_HUFF   = 0,      /// Huffman table is used for coding macroblocks
+    IVI_MB_HUFF   = 0,      ///< Huffman table is used for coding macroblocks
     IVI_BLK_HUFF  = 1       /// Huffman table is used for coding blocks
 };
 
diff --git a/libavfilter/vf_deshake.c b/libavfilter/vf_deshake.c
index 00e7472f67..107b78a7d1 100644
--- a/libavfilter/vf_deshake.c
+++ b/libavfilter/vf_deshake.c
@@ -88,7 +88,7 @@ typedef struct Transform {
 
 typedef struct DeshakeContext {
     const AVClass *class;
-    int counts[2*MAX_R+1][2*MAX_R+1]; /// < Scratch buffer for motion search
+    int counts[2*MAX_R+1][2*MAX_R+1]; ///< Scratch buffer for motion search
     double *angles;            ///< Scratch buffer for block angles
     unsigned angles_size;
     AVFrame *ref;              ///< Previous frame
diff --git a/libavformat/rmdec.c b/libavformat/rmdec.c
index 0f1534b582..d0062c47bb 100644
--- a/libavformat/rmdec.c
+++ b/libavformat/rmdec.c
@@ -51,8 +51,8 @@ struct RMStream {
     int64_t audiotimestamp; ///< Audio packet timestamp
     int sub_packet_cnt; // Subpacket counter, used while reading
     int sub_packet_size, sub_packet_h, coded_framesize; ///< Descrambling parameters from container
-    int audio_framesize; /// Audio frame size from container
-    int sub_packet_lengths[16]; /// Length of each subpacket
+    int audio_framesize; ///< Audio frame size from container
+    int sub_packet_lengths[16]; ///< Length of each subpacket
     int32_t deint_id;  ///< deinterleaver used in audio stream
 };
 
-- 
2.43.0

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

[FFmpeg-devel] [PATCH 2/3] avcodec/ivi: Make comments more Doxygen-friendly

[Andrew Sayers]

Doxygen eats the newline in the first comment, making it harder to read.
Join the lines and add a comma, so source and documentation are equally readable.

Doxygen only associates the second comment with cust_dec.
The comments for cust_dec and cust_tab make perfect sense without it,
so downgrade it to a non-doxygen "//" comment.

The third comment was missed by the command in the previous commit,
because it (correctly but uniquely) doesn't have a trailing comma.

Signed-off-by: Andrew Sayers <ffmpeg-devel@pileofstuff.org>
---
 libavcodec/ivi.h | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/libavcodec/ivi.h b/libavcodec/ivi.h
index ec54f65f30..afc3ec2a75 100644
--- a/libavcodec/ivi.h
+++ b/libavcodec/ivi.h
@@ -61,18 +61,17 @@ typedef struct IVIHuffDesc {
  *  macroblock/block huffman table descriptor
  */
 typedef struct IVIHuffTab {
-    int32_t     tab_sel;    ///< index of one of the predefined tables
-                            /// or "7" for custom one
+    int32_t     tab_sel;    ///< index of one of the predefined tables, or "7" for custom one
     VLC         *tab;       ///< pointer to the table associated with tab_sel
 
-    /// the following are used only when tab_sel == 7
+    // the following are used only when tab_sel == 7
     IVIHuffDesc cust_desc;  ///< custom Huffman codebook descriptor
     VLC         cust_tab;   ///< vlc table for custom codebook
 } IVIHuffTab;
 
 enum {
     IVI_MB_HUFF   = 0,      ///< Huffman table is used for coding macroblocks
-    IVI_BLK_HUFF  = 1       /// Huffman table is used for coding blocks
+    IVI_BLK_HUFF  = 1       ///< Huffman table is used for coding blocks
 };
 
 
-- 
2.43.0

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

[FFmpeg-devel] [PATCH 3/3] avcodec/avcodec: Downgrade multi-member comment to non-Doxygen comment

[Andrew Sayers]

Doxygen only associates this comment with "pts_correction_num_faulty_pts",
causing it to display incorrectly.

Signed-off-by: Andrew Sayers <ffmpeg-devel@pileofstuff.org>
---
 libavcodec/avcodec.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
index 58c581a5c0..8aa1356b8c 100644
--- a/libavcodec/avcodec.h
+++ b/libavcodec/avcodec.h
@@ -1827,7 +1827,7 @@ typedef struct AVCodecContext {
      */
     const struct AVCodecDescriptor *codec_descriptor;
 
-    /**
+    /*
      * Current statistics for PTS correction.
      * - decoding: maintained and used by libavcodec, not intended to be used by user apps
      * - encoding: unused
-- 
2.43.0

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] [PATCH 0/3] Fix /// comments that should be ///<

[Stefano Sabatini]

On date Wednesday 2024-02-28 17:09:38 +0000, Andrew Sayers wrote:
> This is the first in a planned series of patch series aimed at
> fixing documentation issues, especially doxygen rendering.
> I hope to post more as time allows in the coming days.
> 
> The first patch reflects the output of a `sed` command,
> further patches fix edge cases not covered by `sed`.
> Splitting commits this way allows merge conflicts
> to be resolved by throwing the old commit away,
> then running the command in the commit message.
> 
> Andrew Sayers (3):
>       all: Fix /// comments that should be ///<
>       avcodec/ivi: Make comments more Doxygen-friendly
>       avcodec/avcodec: Downgrade multi-member comment to non-Doxygen comment
> 
>  libavcodec/avcodec.h     | 10 +++++-----
>  libavcodec/bsf/noise.c   | 24 ++++++++++++------------
>  libavcodec/ivi.h         | 15 +++++++--------
>  libavfilter/vf_deshake.c |  2 +-
>  libavformat/rmdec.c      |  4 ++--
>  5 files changed, 27 insertions(+), 28 deletions(-)

Will apply, thanks.
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] [PATCH 0/3] Fix /// comments that should be ///<

[Andreas Rheinhardt]

Stefano Sabatini:
> On date Wednesday 2024-02-28 17:09:38 +0000, Andrew Sayers wrote:
>> This is the first in a planned series of patch series aimed at
>> fixing documentation issues, especially doxygen rendering.
>> I hope to post more as time allows in the coming days.
>>
>> The first patch reflects the output of a `sed` command,
>> further patches fix edge cases not covered by `sed`.
>> Splitting commits this way allows merge conflicts
>> to be resolved by throwing the old commit away,
>> then running the command in the commit message.
>>
>> Andrew Sayers (3):
>>       all: Fix /// comments that should be ///<
>>       avcodec/ivi: Make comments more Doxygen-friendly
>>       avcodec/avcodec: Downgrade multi-member comment to non-Doxygen comment
>>
>>  libavcodec/avcodec.h     | 10 +++++-----
>>  libavcodec/bsf/noise.c   | 24 ++++++++++++------------
>>  libavcodec/ivi.h         | 15 +++++++--------
>>  libavfilter/vf_deshake.c |  2 +-
>>  libavformat/rmdec.c      |  4 ++--
>>  5 files changed, 27 insertions(+), 28 deletions(-)
> 
> Will apply, thanks.

Please don't. Anton intends to remove the pts_correction fields with the
bump and so this is unnecessary and will just cause a rebase conflict.

- Andreas

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] [PATCH 0/3] Fix /// comments that should be ///<

[Stefano Sabatini]

On date Monday 2024-03-04 17:49:27 +0100, Andreas Rheinhardt wrote:
> Stefano Sabatini:
> > On date Wednesday 2024-02-28 17:09:38 +0000, Andrew Sayers wrote:
> >> This is the first in a planned series of patch series aimed at
> >> fixing documentation issues, especially doxygen rendering.
> >> I hope to post more as time allows in the coming days.
> >>
> >> The first patch reflects the output of a `sed` command,
> >> further patches fix edge cases not covered by `sed`.
> >> Splitting commits this way allows merge conflicts
> >> to be resolved by throwing the old commit away,
> >> then running the command in the commit message.
> >>
> >> Andrew Sayers (3):
> >>       all: Fix /// comments that should be ///<
> >>       avcodec/ivi: Make comments more Doxygen-friendly
> >>       avcodec/avcodec: Downgrade multi-member comment to non-Doxygen comment
> >>
> >>  libavcodec/avcodec.h     | 10 +++++-----
> >>  libavcodec/bsf/noise.c   | 24 ++++++++++++------------
> >>  libavcodec/ivi.h         | 15 +++++++--------
> >>  libavfilter/vf_deshake.c |  2 +-
> >>  libavformat/rmdec.c      |  4 ++--
> >>  5 files changed, 27 insertions(+), 28 deletions(-)
> > 
> > Will apply, thanks.
> 

> Please don't. Anton intends to remove the pts_correction fields with the
> bump and so this is unnecessary and will just cause a rebase conflict.

Too late, sorry, hopefully the rebase should not too hard to fix (also
there are more changes unrelated to pts_correction we want to keep).

Let me know if we should hold header changes to prevent rebase conflicts
at this stage.
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".