php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Bug #52314 Incorrect use of classsynopsisinfo
Submitted: 2010-07-12 12:17 UTC Modified: 2012-04-06 17:37 UTC
Votes:1
Avg. Score:5.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:1 (100.0%)
From: RQuadling at GMail dot com Assigned: bjori (profile)
Status: Closed Package: Doc Build problem
PHP Version: Irrelevant OS: n/a
Private report: No CVE-ID: None
 [2010-07-12 12:17 UTC] RQuadling at GMail dot com
Description:
------------
Looking at most of the OOP class pages ...

3 chosen at random :
http://docs.php.net/manual/en/class.Phar.php
http://docs.php.net/manual/en/class.datetime.php
http://docs.php.net/manual/en/class.arrayobject.php

There is an empty white box at the top of the class definition.

The issue seems to be due to the first ooclass tag which isn't rendered 
properly.

The xml also has ooclass and oointerface tags inside an classsynopsisinfo. This 
seems to be against the intent of a classsynopsisinfo.

TDG5 (http://www.docbook.org/tdg51/en/html/classsynopsisinfo.html) says 
"Supplementary information in a classsynopsis. See classsynopsis. 

Unlike the other info elements, classsynopsisinfo is not a container for meta-
information. Instead classsynopsisinfo is a verbatim environment for adding 
additional information to a class synopsis."

Also important on this is the processing expectations which are "This element is 
displayed “verbatim”; whitespace and line breaks within this element are 
significant.".

What exactly warrants "Supplementary information" is the issue here. DocBook has 
tags for ooclass and oointerface (and these are in the "1 or more of" sequence 
for classsynopsis) and so have no need to be thought of as "supplementary 
information".

Using classsynopsisinfo to show comments (/* Methods */, /* Constants */, etc.) 
would seem to fit the spirit of this tag.


So ...

<!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>DateTimeZone</classname></ooclass>

<!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <ooclass>
      <classname>DateTimeZone</classname>
     </ooclass>
    </classsynopsisinfo>
<!-- }}} -->
    <classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>integer</type>

should be ...

<!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>DateTimeZone</classname></ooclass>

<!-- }}} -->
    <classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>integer</type>

No need for the classsynopsisinfo with the ooclass tags.


Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2010-10-23 14:51 UTC] kalle@php.net
-Type: Documentation Problem +Type: Bug
 [2012-04-06 17:37 UTC] bjori@php.net
This was fixed a while ago
 [2012-04-06 17:37 UTC] bjori@php.net
-Status: Open +Status: Closed -Assigned To: +Assigned To: bjori
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sat Dec 21 13:01:31 2024 UTC