Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:114293 Return-Path: Delivered-To: mailing list internals@lists.php.net Received: (qmail 10152 invoked from network); 7 May 2021 13:37:38 -0000 Received: from unknown (HELO php-smtp4.php.net) (45.112.84.5) by pb1.pair.com with SMTP; 7 May 2021 13:37:38 -0000 Received: from php-smtp4.php.net (localhost [127.0.0.1]) by php-smtp4.php.net (Postfix) with ESMTP id 18C0B1804B5 for ; Fri, 7 May 2021 06:44:26 -0700 (PDT) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on php-smtp4.php.net X-Spam-Level: X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,NICE_REPLY_A, RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_PASS autolearn=no autolearn_force=no version=3.4.2 X-Spam-Virus: No X-Envelope-From: Received: from mail-wm1-f47.google.com (mail-wm1-f47.google.com [209.85.128.47]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-256) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by php-smtp4.php.net (Postfix) with ESMTPS for ; Fri, 7 May 2021 06:44:25 -0700 (PDT) Received: by mail-wm1-f47.google.com with SMTP id s5-20020a7bc0c50000b0290147d0c21c51so4925545wmh.4 for ; Fri, 07 May 2021 06:44:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to:content-transfer-encoding:content-language; bh=31S3P/dy4WXwdJq+cmD4+UcxCJO1ZqBFrGr6VEWCchM=; b=hMsPAvyjY5LCxaLp068iOAPAUF/trYkLYqPKxQPg4PZ8RJ2LfiOHnQuq/FG+CKNH8I JpRKd08UpYjA79/CB03Iw5NpUKd9CCZc1bi0YbVXOkyz6/N4o2zBom0fotfvy47y1Dc8 IMpR58/afBdVVj1uomZuyRJJIAubsiZHA90ZOL8Pqx4FcfrEo8W6uy7hpz4+Ktmwf5JH DSGYH75TWua/d3QaRfu1UjmcP4FVU8bkKxfqgHgT6POfrjzgQQhWvuzXvwID0d7QCuwf a6iuDL0VBskDqJlVuQp2PwaqGn91jBwJ2NPGxXx+wg2QsWuhXA+i8+5uhHoEeBuTy9sT gwbQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-transfer-encoding :content-language; bh=31S3P/dy4WXwdJq+cmD4+UcxCJO1ZqBFrGr6VEWCchM=; b=M9rnLExt/wexcD2J0/LYgk2yws8tgTyo+VP2s6g8TEscrsEke1uGC/pEOWFq7WVMhR 9kLqXQf+Fdwr1kfNjQtbNT4myLx++o5S9oVM89eFoKKhoXQEcQRf5OfV0iNwqq63xyUe u9Lp0PbYO6wlU3lE5LiS6ZNJDctpVios6vp5i1DumKTySkJKD8Y+RS4hGu7sPz3tTwI2 FHyE4ebI+IZQ5ne7g3OW6NZ4mphzjXk8jLv6ZvlP/umwAI74H5Nj3JlkXE/GqNDqGjUt XdHmfLDPpRaNGk3o93nqZQpDKg3Dz96j9XbuFS7rO1dTy8y4VJHXDaseYSJ1qU86PJYm WeFg== X-Gm-Message-State: AOAM53278irh79sUnex4ct+zdvlgr3d4ABBQKkm7ofUNCNvy0odpYbpl Mp0mvnIDDzHW7OF0776n3x64s7/iHgs= X-Google-Smtp-Source: ABdhPJwuL6Z8KlCj59aSAY2UywkKZUaMSSi/dT7TsGKwCDs+Nbp8j5/4gQGUWoRYPaZabIQ7cdXmAQ== X-Received: by 2002:a05:600c:3515:: with SMTP id h21mr21382959wmq.148.1620395062896; Fri, 07 May 2021 06:44:22 -0700 (PDT) Received: from [192.168.0.22] (cpc104104-brig22-2-0-cust548.3-3.cable.virginm.net. [82.10.58.37]) by smtp.googlemail.com with ESMTPSA id e18sm9063204wrc.85.2021.05.07.06.44.21 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 07 May 2021 06:44:21 -0700 (PDT) To: internals@lists.php.net References: Message-ID: <31cc9af0-35ed-ec2d-7ede-3489fdc3c18b@gmail.com> Date: Fri, 7 May 2021 14:44:19 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.10.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Content-Language: en-GB Subject: Re: [PHP-DEV] PHP Language Specification From: rowan.collins@gmail.com (Rowan Tommins) On 07/05/2021 09:10, Nikita Popov wrote: > If we want to include "writing documentation" > as part of the change process, then it would be much more valuable to write > documentation for php.net, which is used by hundreds of thousands of > developers, rather than the language specification, which is used by a > handful at best. I agree with this. The reality is, the specification is just another form of documentation. When it was written, there was a realistic prospect of two competing implementations needing to agree on new features, but that never happened, so if the spec doesn't agree with the implementation, it's always the spec that's wrong. If we want the behaviour of the language to be better documented, we have existing places for that: * Incorporate formal descriptions from the language spec into the manual. Maybe we need a way of embedding grammar snippets into appropriate chapters. * Document behaviour in edge cases - defaults, error conditions, interactions of options, etc. You don't have to be writing an implementation to want to know that stuff. * Encourage, or require, contributors to write some basic documentation of new features. We have bundled functions and options without even a single sentence in the manual. * Write tests, and label them clearly. If anyone wants to write an alternative implementation, they can run the test suite against it. Regards, -- Rowan Tommins [IMSoP]