Thanks a lot for this great module, it provides a very simple answer to many common use cases.
While working with the Facetapi Bonus, I came accross the implementation of several hooks provided by the Page Title module's API and tried to look for some documentation but couldn't find much about the hooks except what is mentioned on the project page.
Since it seems this has been a recurring request and I would assume it would save quite a lot of time to other developers, I tried putting together some documentation in a page_title.api.php file.
Please find attached to this ticket a patch against the latest page_title-7.x-2.7+1-dev (2012-05-11) to add a new file: page_title.api.php, to document all three Page Title API hooks.
[File attached as: page_title-document-api-hooks-1.patch]
This issue and patch are supposed to be for the 7.x-2.x branch, but they could certainly be applied to the 6.x-2.x branch as well, which provides the same API hooks.
I have tried to detail the implementation, parameters, returns, etc... for all three Page Title API hooks and provide some basic examples taken from module's implementations in the modules folder, for example from node.page_title.inc or taxonomy.page_title.inc.
Another very good example could be found in the Facetapi Bonus module, as mentioned above.
I actually ended up learning and lot about the module and how it works, in particular, before it wasn't clear at all for me how
hook_page_title_alter could be implemented or would be triggered.
I have also found several other related areas where the module could be improved, for example on coding standards but I guess this would have to be posted in another ticket.
The contents of this patch and API documentation was rather substantial to write and review at once, by myself alone, so I would certainly assume it could still be improved, there might still be mistakes (typos, wrong language/words/terms/vocabulary/punctuation, etc...) and I would greatly appreciate any feedbacks, comments, help to review or questions that could contribute to making this patch better.
I assumed this initial draft could already provide a good basis/foundation to start getting some API documentation in module's code.
As a side note, I would tend to assume that the documentation should have been added in the same commits as when the hook calls were implemented in code. This way hooks triggered or provided in module's code wouldn't remain undocumented.
Lastly, I couldn't help myself to do a very quick fix to a typo I crossed while checking the code:
in page_title.module, line 539:
// Give other modules the oppertunity to use hook_page_title_alter().
was changed to: [oppertunity ==> opportunity]
// Give other modules the opportunity to use hook_page_title_alter().
and it is also included in attached patch.
Could you please let me know if I overlooked or missed anything in the current Page Title module (and its API), in terms of whether the documentation is correct or not?
Please let me know if you would have any questions on any points/code/aspects mentioned in this ticket, I would surely be glad to provide more information.
I would greatly appreciate some help from module maintainers and if any of you could take a bit of time to look into the patch to give me your feedback/opinion on this documentation request.
Any feedback, testing, changes, recommendations would be highly appreciated.
Thanks to all in advance.
|#1||Updated patch for quick fix of coding standards.||8.08 KB||DYdave|
|Patch to add initial draft documentation for all three Page Title API hooks.||8.08 KB||DYdave|