Status of php.net documentation

[Girgias]

Hello,

I've been doing some QA work on the php.net docs and I'm wondering how up to date the Solr ones are. The main thing which prompted me to reach out is that, at least, SolrDocument has empty documentation for __construct() and --destruct() which if they don't do anything should be removed.

So how maintained are the docs on php.net or are the docs located somewhere else in which case it might make sense to remove it from the official php.net docs.

[cmb69]

SolrDocument::__construct() and ::__destruct() apparently do something, so they should be documented (at least we could add &warn.undocumented.func;).

[omars44]

@Girgias I'm gonna have a look, thanks for raising this

[Girgias]

@Girgias I'm gonna have a look, thanks for raising this

If you need help for the php.net ones which are located in php/doc-en let me know :)

[omars44]

@Girgias I do if you have some cheatsheet (bunch of commands to build), of sorts. I was a away, and have to read the docs to... build the docs lol, those lazy programmers lol

ref: https://github.com/php/doc-base/blob/master/README.md

[Girgias]

The important one is php ./path_to_/doc-base/configure.php and have the doc-en repo actually be in a folder named en because of hard coded paths.

PhD is not required to vizualize but I'll find you the command :)

[omars44]

@Girgias I managed to make some additions but not sure how to compile and see my changes in html locally

[Girgias]

Running the PhD/render.php script with the following command you do the the trick:

php -dmemory_limit="1024M" render.php -P PHP -d ../base/.manual.xml -f xhtml -f bigxhtml -f php -f tocfeed --output ../output_bightml -r

And should show you the HTML layout that looks kinda like php.net. :)

[omars44]

@Girgias I'm back to docs finally, I don't agree that we should remove constructors, because they do exist and they are used internally. they are just not beneficial in the userland. I'm happy to hear any counter-arguments, or if there is a consensus about this issue that I'm not aware of.

However you brought to my attention to revisit the docs which is really helpful, as I discovered a problem while updating it to the latest. there is an old class that is not documented 🙈

[omars44]

@Girgias Hey, do you know if there is a way to add external links to a method documentation page, 'Useful Links' section of sorts, in our case, most of SolrQuery methods relies on Solr Server's Parameters, which have documentation of their own, so it would be helpful for the reader to have a reference link to Solr Docs to understand the parameters in their context, and not just the method.

[Girgias]

@Girgias Hey, do you know if there is a way to add external links to a method documentation page, 'Useful Links' section of sorts, in our case, most of SolrQuery methods relies on Solr Server's Parameters, which have documentation of their own, so it would be helpful for the reader to have a reference link to Solr Docs to understand the parameters in their context, and not just the method.

You can use a <link xlink:href="URL">content of link</link> with the xmlns:xlink="http://www.w3.org/1999/xlink" namespace, usually such URLs are stored in the entities/global.ent file of the doc-base repo.

[Girgias]

@Girgias Hey, do you know if there is a way to add external links to a method documentation page, 'Useful Links' section of sorts, in our case, most of SolrQuery methods relies on Solr Server's Parameters, which have documentation of their own, so it would be helpful for the reader to have a reference link to Solr Docs to understand the parameters in their context, and not just the method.

Not an issue, however, they should use the markup with <constructorsynopsis> tag which requires updating the class pages to XInclude it at the beginning.