Skip to content

Improve docblocks #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jun 17, 2014
Merged

Improve docblocks #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
87c283f
Pass through php -l
bjori Jun 17, 2014
d3e04fb
Add a bootstrapping file that includes all other files
bjori Jun 17, 2014
7e8d2c2
Fix docblock param order
bjori Jun 17, 2014
ae182d1
Fix return value
bjori Jun 17, 2014
d587a84
Lets not start out with complicated zpp...
bjori Jun 17, 2014
19fb9bf
Change some @see into @param or @param and add some descriptions
bjori Jun 17, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions docs/api/MongoDB/Command/CommandCursor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

use MongoDB\Cursor;
use MongoDB\CursorId;
use Mongodb\Server;

/**
* Cursor implementation that may be constructed from values found in a
Expand Down Expand Up @@ -34,37 +35,42 @@ public function __construct(Server $server, CursorId $cursorId, array $firstBatc
$this->firstBatch = $firstBatch;
}

// Iterator methods...

/**
* @return Cursor::getId()
* @return CursorId
*/
public function getId()
{
return $this->cursorId;
}

/**
* @see Cursor::getServer()
* @return Server Server from which the cursor originated
*/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When implementing an interface or overriding a method, I do this instead of copy/pasting. It's up to you.

Some projects use @inheritDoc, but I've had mixed results with it and this is more explicit, as any generator should create a hyperlink to the referenced doc block.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mmmh.
I'm using this data to create the extension skeleton. Not really keen on making a full fledged javadoc parser :)

public function getServer()
{
return $this->server;
}

/**
* @see Cursor::isDead()
* @return boolean Whether the cursor is exhausted and has no more results
*/
public function isDead()
{
// Return whether the cursor is exhausted and has no more results
}

/**
* @see \MongoDB\Cursor::setBatchSize()
* @param integer $batchSize
*/
public function setBatchSize($batchSize)
{
$this->batchSize = (integer) $batchSize;
}

/* Cursor is an iterator */
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you remove // Iterator methods... earlier in this class?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

public function current() {}
public function next() {}
public function key() {}
public function valid() {}
public function rewind() {}
}
2 changes: 1 addition & 1 deletion docs/api/MongoDB/CursorId.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ final class CursorId
// $id is an internal uint64_t value instead of a class property

/**
* @param integer|string $id
* @param string $id
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see why this shouldn't be able to take an integer, provided the architecture supports it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because we'll then end up with the "if 32bit? code-rot else tested code that we know how works"
It better be a consistent thing imo.

Why should it be an integer anyway? Will it always be an int in the future? can't it just as well be mongoid? Or something that can be traced back to the particular server/shard?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If an integer is passed, ZPP would implicitly cast it to a string, wouldn't it?

Even if we document it as integer|string, I don't think we need to concern ourselves with what architecture our users are on. If they're 32-bit, and the cursor ID they're referring to can be expressed in 32 bits, then that's great; otherwise, they're passing the constructor an incorrect value.

I just realized we don't have any API example of where the CursorId comes from. As-is, I expect they need to check the command result document and construct it accordingly. Will that value have been converted to a MongoInt64 already on a 32-bit platform and left as an integer on 64-bit?

If so, MongoInt64 would already work because it has a toString() method.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why can't it be a string in both cases?
I find MongoInt64 along with mongo.long_as_object and mongo.native_long extremely confusing and really don't want it.

*/
public function __construct($id)
{
Expand Down
10 changes: 10 additions & 0 deletions docs/api/MongoDB/Manager.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@
final class Manager
{
/**
* Constructs a new Manager
*
* @param string $uri Connection URI
* @param array $options Connection options (e.g. auth, socket timeouts)
* @param array $driverOptions Driver options (e.g. stream contexts)
Expand All @@ -35,6 +37,8 @@ public function __construct($uri, array $options = array(), array $driverOptions
}

/**
* Creates new Manager from a list of servers
*
* @param Server[] $servers
* @return Manager
*/
Expand All @@ -50,6 +54,8 @@ static public function createFromServers(array $servers)
}

/**
* Execute a command
*
* @param string $db
* @param Command $command
* @param ReadPreference $readPreference
Expand All @@ -72,6 +78,8 @@ public function executeCommand($db, Command $command, ReadPreference $readPrefer
}

/**
* Execute a Query
*
* @param string $namespace
* @param Query $query
* @param ReadPreference $readPreference
Expand All @@ -92,6 +100,8 @@ public function executeQuery($namespace, Query $query, ReadPreference $readPrefe
}

/**
* Executes a write operation batch (e.g. insert, update, delete)
*
* @param string $namespace
* @param WriteBatch $batch
* @param array $writeOptions Ordering and write concern options (default: {"ordered": true, "w": 1})
Expand Down
2 changes: 1 addition & 1 deletion docs/api/MongoDB/Query/Query.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ final class Query
* @param array|object $query Query document
* @param array|object $selector Selector document
* @param integer $flags Query flags
* @param integer $limit Limit
* @param integer $skip Skip
* @param integer $limit Limit
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is limit more common than skip? I wonder if we should swap these.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

limit 10 skip 15 reads like a overflow and weird api.
also in sql it is "skip, limit" I think?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noted. Fine as-is.

*/
public function __construct($query, $selector, $flags, $skip, $limit)
{
Expand Down
20 changes: 14 additions & 6 deletions docs/api/MongoDB/Query/QueryCursor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

use MongoDB\Cursor;
use MongoDB\CursorId;
use Mongodb\Server;

/**
* Cursor implementation that is returned after executing a Query.
Expand All @@ -21,6 +22,8 @@ final class QueryCursor implements Cursor
private $cursorId;

/**
* Construct a new QueryCursor
*
* @param Server $server
* @param CursorId $cursorId
*/
Expand All @@ -30,37 +33,42 @@ public function __construct(Server $server, CursorId $cursorId)
$this->cursorId = $cursorId;
}

// Iterator methods...

/**
* @see Cursor::getId()
* @return CursorId
*/
public function getId()
{
return $this->cursorId;
}

/**
* @see Cursor::getServer()
* @return Server Server from which the cursor originated
*/
public function getServer()
{
return $this->server;
}

/**
* @see Cursor::isDead()
* @return boolean Whether the cursor is exhausted and has no more results
*/
public function isDead()
{
// Return whether the cursor is exhausted and has no more results
}

/**
* @see Cursor::setBatchSize()
* @param integer $batchSize
*/
public function setBatchSize($batchSize)
{
$this->batchSize = (integer) $batchSize;
}

/* Cursor is an iterator */
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Delete // Iterator methods... above.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

public function current() {}
public function next() {}
public function key() {}
public function valid() {}
public function rewind() {}
}
2 changes: 1 addition & 1 deletion docs/api/MongoDB/Write/DeleteBatch.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ final class DeleteBatch implements WriteBatch
private $documents;

/**
* @see WriteBatch::add()
* @param array|object $document Operation/document to add to the batch
*/
public function add($document)
{
Expand Down
2 changes: 1 addition & 1 deletion docs/api/MongoDB/Write/InsertBatch.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ final class InsertBatch implements WriteBatch
private $documents;

/**
* @see WriteBatch::add()
* @param array|object $document Operation/document to add to the batch
*/
public function add($document)
{
Expand Down
2 changes: 1 addition & 1 deletion docs/api/MongoDB/Write/UpdateBatch.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ final class UpdateBatch implements WriteBatch
private $documents;

/**
* @see WriteBatch::add()
* @param array|object $document Operation/document to add to the batch
*/
public function add($document)
{
Expand Down
22 changes: 22 additions & 0 deletions docs/bootstrap.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<?php
include "api/MongoDB/Cursor.php";
include "api/MongoDB/CursorId.php";
include "api/MongoDB/Manager.php";
include "api/MongoDB/ReadPreference.php";
include "api/MongoDB/Server.php";
include "api/MongoDB/Query/Query.php";
include "api/MongoDB/Query/QueryCursor.php";
include "api/MongoDB/Command/Command.php";
include "api/MongoDB/Command/CommandCursor.php";
include "api/MongoDB/Command/CommandResult.php";
include "api/MongoDB/Write/WriteBatch.php";
include "api/MongoDB/Write/WriteResult.php";
include "api/MongoDB/Write/DeleteBatch.php";
include "api/MongoDB/Write/DeleteResult.php";
include "api/MongoDB/Write/GeneratedId.php";
include "api/MongoDB/Write/InsertBatch.php";
include "api/MongoDB/Write/InsertResult.php";
include "api/MongoDB/Write/UpdateBatch.php";
include "api/MongoDB/Write/UpdateResult.php";
include "api/MongoDB/Write/WriteConcernError.php";
include "api/MongoDB/Write/WriteError.php";