Syntax Error in Example

[DavidBruchmann]

In Doctrine\DBAL\Query\QueryBilder the semikolon in the line ->where('u.id = :user_id'); is wrong:

/**
 * Turns the query being built into a bulk delete query that ranges over
 * a certain table.
 *
 * <code>
 *     $qb = $conn->createQueryBuilder()
 *         ->delete('users', 'u')
 *         ->where('u.id = :user_id');
 *         ->setParameter(':user_id', 1);
 * </code>
 *
 * @param string $delete The table whose rows are subject to the deletion.
 * @param string $alias  The table alias used in the constructed query.
 *
 * @return $this This QueryBuilder instance.
 */
public function delete($delete = null, $alias = null)
{
...

[morozov]

Honestly, I'm not a fan of code snippets in phpDocs. They are hard to validate, they are not highlighted in the editor, etc. Why don't we get rid of it at all and make sure it's documented in docs/?

[Ocramius]

I think these are are awesome on the builder: found them very useful multiple times (instead of having to go to the docs), but no hard feelings if you'd rather have them gone.

[Majkl578]

It could be possible to implement a PHPCS sniff to lint contents of <code> within phpDocs.

[DavidBruchmann]

I propose to fix the error in this issue.
For general handling or decision if to remove those comments completely open another issue.
Also parsing code in comments is another issue - even the hint might be useful.
Separated issues have a clear headline explaining the issue, so people who are interested really look at it. In this headline here it can't be supposed which decision seems being on the desk.

Nevertheless, thanks for the input, hope you never feel discouraged by my comment ;-)

[morozov]

@DavidBruchmann please send us a pull request correcting the error.

[morozov]

It could be possible to implement a PHPCS sniff to lint contents of <code> within phpDocs.

@Majkl578 it still makes it possible to have obsolete examples:

dbal/lib/Doctrine/DBAL/Platforms/AbstractPlatform.php

Lines 933 to 939 in 26d3587

	* Example:
	* <code>
	* $q = new Doctrine_Query();
	* $e = $q->expr;
	* $q->select('*')->from('table')
	* ->where($e->eq('id', $e->not('null'));
	* </code>

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.