mbox series

[FFmpeg-devel,0/2] Harmonise comments about ownership/meaning

Message ID 20240229162424.850294-1-ffmpeg-devel@pileofstuff.org
Headers show
Series Harmonise comments about ownership/meaning | expand

Message

Andrew Sayers Feb. 29, 2024, 4:23 p.m. UTC 
There seems to be a couple of documentation conventions in the code:

  /**
   * - encoding: (who sets this in encoding context)
   * - decoding: (who sets this in decoding context)
   */
  int foo;

  /**
   * Encoding: (meaning in encoding context)
   * Decoding: (meaning in decoding context)
   */
  int bar;

These are very useful, but the layout causes some issues:

1. (slightly) different layouts are used in some places
2. doxygen renders the "meaning" layout as one big paragraph, which is hard to read
3. the layouts are quite similar, so it can be hard to tell at a glance
   whether a given piece of documentation is talking about ownership or meaning

For a good example of this issue, please see [1].

Harmonise layouts and propose a new layout for meanings:

  /**
   * *Encoding:*
   *
   *   Meaning in encoding context
   *
   * *Decoding:*
   *
   *   Meaning in decoding context
   */

I hope this isn't too forward for my second day around here, but IMHO
this would significantly improve readability.

[1] https://ffmpeg.org/doxygen/6.0/structAVCodecContext.html#a948993adfdfcd64b81dad1151fe50f33

Andrew Sayers (2):
      avformat: harmonise "- {decoding,encoding,demuxing,muxing}: " comments
      all: harmonise "{Decoding,Encoding,Audio,Video}:" comments

 libavcodec/avcodec.h   | 19 +++++++----
 libavformat/avformat.h | 89 +++++++++++++++++++++++++++-----------------------
 2 files changed, 62 insertions(+), 46 deletions(-)