Criteria::lockForUpdate documentation is missing?

[profuel]

I struggle to use a newer way of locks. Who can help?
https://github.com/propelorm/Propel2/blob/master/src/Propel/Runtime/ActiveQuery/Criteria.php#L1400
If there's a better place to ask for this, happy to do so - just guide me!

Thanks!

[kasparsatke]

Yes, this function lacks documentation.

It was introduced together with other lock functions in PR #1658.

There is a little documentation on the intent in this PR and links to the underlying DB logic but also a call for proper documentation from propelorm/propelorm.github.com#417 in the documentation repo.

What I really don't understand is why this function you mention is not covered at all in the official website and documentation https://propelorm.org/documentation/ within the source code repo https://github.com/propelorm/propelorm.github.com

Instead, along with a lot of other crucial documentation, this file is documented only under https://api.propelorm.org using a different source code repo: https://github.com/propelorm/api.propelorm.org

In theory, your documention should be in this file: https://api.propelorm.org/2.0-master/Propel/Runtime/ActiveQuery/Criteria.html

Unfortunately, the API repo has last been updated almost 11 years ago. As I understand it, it once was generated automatically also 11 years ago with https://github.com/FriendsOfPHP/Sami and then received only a few commits afterwards. Although the Sami repo is also grandfathered since 2019 maybe it is still possible to get this running again to update the API docs for all the changes in the API within the last 11 years.

Besides a proper update for the API docs (be it automatic or manual) - what I actually find really important is to integrate the API documentation into the main documentation and if possible, even merge the repos.

Today, there is only one tiny link in https://propelorm.org/documentation/ pointing to the API docs. I always overlooked this link until today because I was often times looking for functions or constants concerning Criteria or ModelCriteria and finally had to google up the relevant pages when I had a question as most of this stuff is not really covered in the 2.x main docs. Some stuff is even better explained in the old 1.x docs 😱. Also the proper TableMap documentation I could only find via googling the relevant API doc page. And these API doc pages are most often not under the top results if you google for something specific. Granted - I now should finally bookmark this stuff 😁.

Saying this, I would love to have the documentation as a whole unified, streamlined and updated.

If anyone is reading this comment who has a say on this, please prodive your opinion if/how this can be accomplished.

All the best,
Kaspar.