From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 5063F48EFB for ; Thu, 29 Feb 2024 16:24:35 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 5986F68D19F; Thu, 29 Feb 2024 18:24:34 +0200 (EET) Received: from alt2.a-painless.mh.aa.net.uk (alt2.a-painless.mh.aa.net.uk [81.187.30.51]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 3473068D113 for ; Thu, 29 Feb 2024 18:24:28 +0200 (EET) Received: from c.e.9.3.3.0.b.1.e.3.4.b.6.2.c.9.0.5.8.0.9.1.8.0.0.b.8.0.1.0.0.2.ip6.arpa ([2001:8b0:819:850:9c26:b43e:1b03:39ec] helo=andrews-2024-laptop.lan) by painless-a.thn.aa.net.uk with esmtp (Exim 4.96) (envelope-from ) id 1rfjCt-00DkRE-1T for ffmpeg-devel@ffmpeg.org; Thu, 29 Feb 2024 16:24:27 +0000 From: Andrew Sayers To: ffmpeg-devel@ffmpeg.org Date: Thu, 29 Feb 2024 16:23:05 +0000 Message-ID: <20240229162424.850294-1-ffmpeg-devel@pileofstuff.org> X-Mailer: git-send-email 2.43.0 MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 0/2] Harmonise comments about ownership/meaning X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: 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(-) _______________________________________________ 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".