Skip to content

Commit

Permalink
Docblocks.
Browse files Browse the repository at this point in the history
  • Loading branch information
@paragonie-security
paragonie-security committed Mar 4, 2018
1 parent e2cd55b commit 785723a
Show file tree
Hide file tree
Showing 4 changed files with 17 additions and 2 deletions.
4 changes: 4 additions & 0 deletions src/Keys/AsymmetricPublicKey.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ public function __construct(

/**
* @return string
* @throws \TypeError
*/
public function encode(): string
{
Expand All @@ -56,7 +57,10 @@ public function encode(): string

/**
* @param string $encoded
*
* @return self
* @throws \Exception
* @throws \TypeError
*/
public static function fromEncodedString(string $encoded): self
{
Expand Down
1 change: 1 addition & 0 deletions src/Keys/AsymmetricSecretKey.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ public static function generate(ProtocolInterface $protocol = null): self

/**
* @return string
* @throws \TypeError
*/
public function encode(): string
{
Expand Down
6 changes: 5 additions & 1 deletion src/ProtocolCollection.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ public function __construct(ProtocolInterface ...$protocols)

/**
* Does the collection contain the given protocol
* @param ProtocolInterface $protocol
*
* @return bool
*/
Expand Down Expand Up @@ -89,7 +90,7 @@ public static function throwIfUnsupported(ProtocolInterface $protocol)
*/
public static function protocolFromHeader(string $header): ProtocolInterface {
if (empty(self::$headerLookup)) {
/** @var string $protocolClass */
/** @var ProtocolInterface $protocolClass */
foreach (self::WHITELIST as $protocolClass) {
self::$headerLookup[$protocolClass::header()] = new $protocolClass;
}
Expand All @@ -106,6 +107,7 @@ public static function protocolFromHeader(string $header): ProtocolInterface {
* Get a collection of all supported protocols
*
* @return self
* @throws InvalidVersionException
*/
public static function default(): self
{
Expand All @@ -123,6 +125,7 @@ function (string $p): ProtocolInterface {
* Get a collection containing protocol version 1.
*
* @return self
* @throws InvalidVersionException
*/
public static function v1(): self
{
Expand All @@ -133,6 +136,7 @@ public static function v1(): self
* Get a collection containing protocol version 2.
*
* @return self
* @throws InvalidVersionException
*/
public static function v2(): self
{
Expand Down
8 changes: 7 additions & 1 deletion src/Purpose.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ public function __construct(string $rawString)
* Create a local purpose.
*
* @return self
* @throws InvalidPurposeException
*/
public static function local(): self
{
Expand All @@ -90,6 +91,7 @@ public static function local(): self
* Create a public purpose.
*
* @return self
* @throws InvalidPurposeException
*/
public static function public(): self

This comment has been minimized.

Sign in to view

Copy link
@aidantwoods

aidantwoods Mar 4, 2018

Contributor

Strictly speaking these types of named constructors should be non-fallible because they construct whitelisted cases. Though I can see a type checker would think they could throw since they contain calls to __construct, which of course may throw (I'm not sure if any editors proactively check this and complain?). This is a bit of an unfortunate side effect of PHP only permitting one "real" constructor; ideally these could be separate constructors in their own right and could thus construct a valid instance directly.

I'm not sure if it is worth removing the @throws to communicate to a user that this method is guaranteed to succeed? (i.e. the user shouldn't be having to think about putting try-catch blocks around these).
(also see: Purpose::local(), ProtocolCollection::default(), ProtocolCollection::v1(), and ProtocolCollection::v2())
{
Expand All @@ -100,7 +102,9 @@ public static function public(): self
* Given a SendingKey, retrieve the corresponding Purpose.
*
* @param SendingKey $key
*
* @return self
* @throws InvalidPurposeException
*/
public static function fromSendingKey(SendingKey $key): self
{
Expand All @@ -117,7 +121,9 @@ public static function fromSendingKey(SendingKey $key): self
* Given a ReceivingKey, retrieve the corresponding Purpose.
*
* @param ReceivingKey $key
*
* @return self
* @throws InvalidPurposeException
*/
public static function fromReceivingKey(ReceivingKey $key): self
{
Expand All @@ -133,7 +139,7 @@ public static function fromReceivingKey(ReceivingKey $key): self
/**
* Compare the instance with $purpose in constant time.
*
* @param self $Purpose
* @param self $purpose
* @return bool
*/
public function equals(self $purpose): bool
Expand Down

0 comments on commit 785723a

Please sign in to comment.