[WIP] Doc updates; fix #964

ctrlaltca commented 1 year ago

This PR replaces all < code > tags with markdown tags in phpdoc comments. The Prism js library has been included in prado-phpdoc-template to enable syntax highlight. It looks some more fixes are needed, eg. most link tags seems to be currently broken.

belisoful commented 1 year ago

Can you write a line or two about the issues you have encountered with @link? and why the move to @see. No problems, just trying to understand the bigger picture.

ctrlaltca commented 1 year ago

Can you write a line or two about the issues you have encountered with @link? and why the move to @see. No problems, just trying to understand the bigger picture.

In the "old times" only @link existed, and it could accept both an URL or a class/method/variable name . In the current specs @link can be used only for urls, and @see must be used for references to classes/methods etc.. There are a few more complications:

in the "old times" all the classes lives in the global namespace, so you didn't need to ensure they are visible from the context of the phpdoc (eg. MyClass instead of \Namespace\To\MyClass)
phpdoc 1.0/apigen were able to automatically resolve method names of the current class (or inherited), so you didn't need to prefix them with the class name or add the parenthesis (eg. "setName" instead of "MyClass::setname()"). Nowadays the parser requires a fully qualified method name.
@link did accept a second, optional parameter with the name to be used for the url (eg. {see setMethodName() MethodName}). The second parameter still exists, but is called "description" and seems to be ignored when {@see } is used inline .

belisoful commented 1 year ago

Thank you for this description! It illuminates your very clear view of this issue (and what I-we "need" to be doing better).

belisoful commented 1 year ago

I don't know if this helps. Yii2 uses the double bracket [[class]] instead of @see class. eg.

 * BaseArrayHelper provides concrete implementation for [[ArrayHelper]].
 * Do not use BaseArrayHelper. Use [[ArrayHelper]] instead.

ctrlaltca commented 1 year ago

Yep, Yii uses its own implementation on top of phpDocumentor: https://github.com/yiisoft/yii2-apidoc

ctrlaltca commented 12 months ago

This is finally ready for merging, the results are already online at https://pradosoft.github.io/docs/manual

pradosoft / prado

[WIP] Doc updates; fix #964 #965