Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:99622
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain oracle.com from 141.146.126.69 cause and error)
To: internals@lists.php.net
References: <e982c2fa-e08c-0970-53d2-c0d6421c9573@fleshgrinder.com>
 <CAF+90c-9uSA+ykCWg_+pSRdZpJcLoScHawK8MWVGGjCx+dA59g@mail.gmail.com>
 <31e715a7-d129-17f0-b870-52bc1ca1715d@fleshgrinder.com>
Message-ID: <af8671d1-9040-39ca-6a8b-fe589d94e2b5@oracle.com>
Date: Fri, 23 Jun 2017 13:12:57 +1000
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:52.0)
 Gecko/20100101 Thunderbird/52.2.0
MIME-Version: 1.0
In-Reply-To: <31e715a7-d129-17f0-b870-52bc1ca1715d@fleshgrinder.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen
From: christopher.jones@oracle.com (Christopher Jones)



On 22/6/17 1:43 am, Fleshgrinder wrote:
> On 6/21/2017 5:38 PM, Nikita Popov wrote:
>> Can you please clarify where functions that are declared in a header and
>> defined in a source file should be documented? I believe the usual
>> recommendation is to document in the source file, because it's closer to
>> the implementation and thus more likely to be updated. On the other hand,
>> documentation in headers only is more useful if you're just browsing code
>> and not using generated output.
>>
>> Nikita
>>
> 
> The documentation should go into the header file. Source files actually
> must not have documentation, because everything in there is private
> anyways. Unless it is exported via a header file that is. Doxygen will
> automatically inherit the documentation (no @inheritDoc necessary),
> because it understands the C code in C mode.

That kind of detail belongs in the RFC.

A link to existing 'prior art' would have rounded the picture out and let
people decide between alternatives of internal vs external doc.
E.g. link to https://wiki.php.net/internals/references

Also, is this for core and for extensions?  Or for core only?  What
about PECL extensions not part of the PHP bundle?

In summary, see point 8 of https://blogs.oracle.com/opal/the-mysterious-php-rfc-process-and-how-you-can-change-the-web

Chris

> 
> Documentation should never document what the implementation does, only
> how it can be used. This gets blurry if you implement a particular,
> standardized algorithm (like the UUIDs) where the actual implementation
> suddenly becomes an important part of information that should go into
> the documentation.
> 
> In other words, refactoring and other changes in a functions body should
> not require changes of the documentation. A usage change usually
> directly translates to a breaking change. A situation in which many
> places require updates (e.g. CHANGELOG, NEWS, ...) and not something a
> dev should do without thinking about the implications of doing so.
> 

-- 
http://twitter.com/ghrd