« Return to Thread: API Documentation Generation

Re: API Documentation Generation

by Daniel O'Connor :: Rate this Message:

On Sun, Mar 25, 2012 at 5:08 PM, Alexey Borzov <borz_off@...> wrote:

> Hi Daniel,
>
>
> On 24.03.2012 13:32, Daniel O'Connor wrote:
>
>> Round 2, with phpdocumentor2, default skin.
>> http://test.pear.php.net/**package/SOAP/docs/latest/<http://test.pear.php.net/package/SOAP/docs/latest/>
>>
>> I did
>> http://test.pear.php.net/**package/Validate_HU/docs/**latest/<http://test.pear.php.net/package/Validate_HU/docs/latest/>
>> http://test.pear.php.net/**package/HTML_Select/docs/**latest/<http://test.pear.php.net/package/HTML_Select/docs/latest/>
>>
>> but they appear to be upset - lacking a @package annotation perhaps?.
>>
>
> Looks rather like a bug in phpdoc2. HTML_Select at least has a @package
> annotation
> https://github.com/pear/HTML_**Select/blob/master/HTML/**Select.php<https://github.com/pear/HTML_Select/blob/master/HTML/Select.php>
>
>

Yeah I did look around further at this, but couldn't figure it out. You can
see the packages generated -
http://test.pear.php.net/package/HTML_Select/docs/latest/packages/ - but
not listed in the index.

There's
https://github.com/phpDocumentor/phpDocumentor2/issues/384
https://github.com/phpDocumentor/phpDocumentor2/issues/356

and I think the thing we are seeing is
https://github.com/phpDocumentor/phpDocumentor2/issues/402

Another half is that DocBook-based documentation links to generated API

> docs via <phd:pearapi /> tags. E.g. I put
>
> <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_**Factory::createElement"
> />
>
> into DocBook and I receive
>
> <a href="http://pear.php.net/**package/HTML_QuickForm2/docs/**
> latest/HTML_QuickForm2/HTML_**QuickForm2_Factory.html#**
> methodcreateElement<http://pear.php.net/package/HTML_QuickForm2/docs/latest/HTML_QuickForm2/HTML_QuickForm2_Factory.html#methodcreateElement>"
> class="apidoclink">HTML_**QuickForm2_Factory::**createElement()</a>
>
> in the resultant HTML.
>
>
> I briefly looked and URLs in phpdoc2 are different from phpdoc. Basically
> we have three options:
> 1) Make phpdoc2 generate same URLs;
> 2) Server-side translation of URLs (mod_rewrite or something);
> 3) Make Phd_PEAR generate phpdoc2-style URLs
>

>
> I think 3) is the most feasible solution, but we should synchronize phpdoc
> and Phd_PEAR upgrades to prevent an obvious issue when links in the
> DocBook-based docs are different from those in API docs.
>

I agree that 3 is the most feasible; and would probably do that first.

But I am worried about incoming links in old documentation a bit.

That URI above has only links we control, which is OK
https://www.google.com.au/webhp?sourceid=chrome-instant&ix=sea&ie=UTF-8&ion=1#q=link%3Ahttp%3A%2F%2Fpear.php.net%2Fpackage%2FHTML_QuickForm2%2Fdocs%2Flatest%2FHTML_QuickForm2%2FHTML_QuickForm2_Factory.html&hl=en&prmd=imvns&filter=0&bav=on.2,or.r_gc.r_pw.r_cp.r_qf.,cf.osb&fp=e53ed314101be7dc&ix=sea&ion=1&biw=1660&bih=989

... but there must be lots of tutorials, blog posts, etc that link to
specific manual pages.

I wonder if we can do an error document which does:
1. You linked to a /latest/ URI, using format which looks like old style
links, but got a 404
2. Redirect the user to /x.y.z/

and
1. You linked to a /x.y.z/ URI, using format which looks like old style
links, but got a 404
2. Redirect user to /(x.y.z) - 1/

It's a pity there's no SELECT * FROM valid_paths or something - doing this
via the filesystem/repeated redirects seems difficult.

« Return to Thread: API Documentation Generation