On Tue, Dec 08, 2015 at 10:59:05AM +0100, Pierre Moreau wrote:
On 09:49 AM - Dec 08 2015, Daniel Vetter wrote:
<para>
Functions which have a non-<code>void</code> return value should have asection called "Returns" explaining the expected return values indifferent cases an their meanings. Currently there's no consensus whetherthat section name should be all upper-case or not, and whether it shouldend in a colon or not. Go with the file-local style. Other common sectionnames are "Notes" with information for dangerous or tricky corner cases,and "FIXME" where the interface could be cleaned up.Why not define (and use) a single style for naming all sections? Old documentation might not use it, but it should be doable to upgrade those old documents.
There is a massive pile of these docs, and there is a slight difference in how vfunc table section headings and function reference section headings are rendered. Given that I figured I'll start modestly.
But if you feel like making this consistent I'd definitely take a patch to do so. Same really for any of the other style guideline issues. Well, after we have some acks on this, and any large-scale style change should first do the RFC patch for this section for discussion to avoid the risk of wasting lots of time. -Daniel