Add return types to method signatures

[dereuromark]

Summary

• Add scalar/simple return types to 243 method signatures across 28 documentation files
• Return types include string, int, float, bool, void, array, mixed, null, self, static, and union types (e.g., string|null, int|false)
• All return types cross-referenced against the CakePHP 5.x source code
• Object return types (Query, Entity, Response, etc.) are intentionally left out for a separate pass

Files Changed

Core Libraries (14 files): app, caching, collections, hash, inflector, logging, number, plugin, security, text, time, xml
Controllers (3 files): controllers, request-response
ORM (4 files): database-basics, deleting-data, saving-data, table-objects
Views (6 files): views, form helper, html helper, paginator helper, text helper, url helper
Development (2 files): configuration, debugging
Console Commands (2 files): input-output, option-parsers

[LordSimal]

Instead of having to keep them up2date manually in here we could make a custom markdown extension which fetches most of that info from the source code. I talked to @josbeir about that and he said that wouldn't be that hard.

[dereuromark]

Sure, I am just getting a head start on that for now, with AI its not that much of work to add for the time being until we have an automated solution.

One open question is the return types of objects, with FQCN or not.
And how to deal with really long lines, as they can become unreadable.

[josbeir]

One open question is the return types of objects, with FQCN or not.

I would not add this if it's a full snippet. Illustrate an import instead.

And how to deal with really long lines, as they can become unreadable.

Can you give an example? For backticked code blocks this is handled with overflow.

[dereuromark]

Illustrate an import instead.

We dont even need that IMO. Its just the docs. If someone wants the full one, they can also see the actual API docs maybe.

[dereuromark]

Once those are merged, we can also more easily see the remaining edge case.
Prelim results on this are:

│ No return type in source │ 13 │ Medium │
├───────────────────────────────────────┼───────┼──────────┤
│ Fluent methods (return $this/static) │ 9 │ Medium │
├───────────────────────────────────────┼───────┼──────────┤
│ Not found / inherited / traits │ 33 │ Low │
├───────────────────────────────────────┼───────┼──────────┤
│ Callback class convention │ 1 │ N/A │
└───────────────────────────────────────┴───────┴──────────┘