From patchwork Fri Jul 31 08:48:51 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nicolas George X-Patchwork-Id: 21398 Return-Path: X-Original-To: patchwork@ffaux-bg.ffmpeg.org Delivered-To: patchwork@ffaux-bg.ffmpeg.org Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by ffaux.localdomain (Postfix) with ESMTP id D883144A82A for ; Fri, 31 Jul 2020 11:49:01 +0300 (EEST) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id B854468B7CF; Fri, 31 Jul 2020 11:49:01 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from nef.ens.fr (nef2.ens.fr [129.199.96.40]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id A5FD468B7CE for ; Fri, 31 Jul 2020 11:48:54 +0300 (EEST) X-ENS-nef-client: 129.199.129.80 ( name = phare.normalesup.org ) Received: from phare.normalesup.org (phare.normalesup.org [129.199.129.80]) by nef.ens.fr (8.14.4/1.01.28121999) with ESMTP id 06V8mrpE005241 for ; Fri, 31 Jul 2020 10:48:54 +0200 Received: by phare.normalesup.org (Postfix, from userid 1001) id C29A4E00CF; Fri, 31 Jul 2020 10:48:53 +0200 (CEST) From: Nicolas George To: ffmpeg-devel@ffmpeg.org Date: Fri, 31 Jul 2020 10:48:51 +0200 Message-Id: <20200731084851.2546-1-george@nsup.org> X-Mailer: git-send-email 2.27.0 MIME-Version: 1.0 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (nef.ens.fr [129.199.96.32]); Fri, 31 Jul 2020 10:48:54 +0200 (CEST) Subject: [FFmpeg-devel] [PATCH] doc/developer: origin of tables should be documented. X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.20 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Tables that were not just written by the code author are not actually source code, otherwise, "recode data..x1 < proprietary.o > source.c" would be enough to launder a proprietary blob into the source code. Documenting the origin of the tables or the methods for their generation is necessary to let other developers take over if the original author is no longer available. Signed-off-by: Nicolas George --- doc/developer.texi | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/developer.texi b/doc/developer.texi index b33cab0fc7..5c698fe9c5 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -216,6 +216,14 @@ please use av_log() instead. @item Casts should be used only when necessary. Unneeded parentheses should also be avoided if they don't make the code easier to understand. + +@item +If the code contains tables of numbers or other data, their origin should be +documented in a comment, so that other developers can rebuild them if +necessary. If they were taken from a reference, include the URL of that +reference. If they were computed by a tool, include the code of the tool. +If they were reverse-engineerd, include an honest attempt at explaining the +methods used. @end itemize @section Editor configuration