phpDocumentor - 常量的可用值列表 [关闭]

Question

我正在编写 API 客户端，我想通过常量定义一个参数的默认值。现在我有这样的：

/**
 * Available: val_1|val_3|val_3|val_4|val_5
 * 
 * @var string
 */
const MY_DEFAULT_VALUE = 'val_1';

但我不确定“枚举”的这种用法是否正确。我找到了do it with method parameters 的方法，但这不是同一个问题。我的方法的定义是：

public function callApi($someParam, $anotherParam = self::MY_DEFAULT_VALUE)

这有什么标准吗？非常感谢。

编辑：我将停止使用抽象值和参数，我将尝试在我正在解决的具体示例中解释它...我正在使用方法 setLanguage() 调用 API，该方法具有可选的参数$lang。我的代码片段：

const DEFAULT_LANGUAGE = 'ENG';
// ...
public function setLanguage($lang = self::DEFAULT_LANGUAGE)

但是我调用的 API 只接受某些语言。基本上，我想在评论中告诉其他程序员的是：“好的，所以你想更改默认语言，但请注意只有这些值是有效的。”。这并不重要，我认为我当前的解决方案也很清楚：

/**
 * Available: ENG|ITA|FRA|DEU|ESP
 * 
 * @var string
 */
const DEFAULT_LANGUAGE = 'ENG';

我只是想知道，这方面是否有一些“好的做法”。

Answer 1

任何时候我需要一个可能的值的指定枚举，我总是使用单独的常量来明确定义它们中的所有，例如const VALUE_1 = 'val_1';，const VALUE_2 = 'val_2';。

至于确定默认值应该是什么，我同意您的方法，即在 callApi() 中使用第二个参数来设置默认值 (callApi())，但要使用其中一个实际常量，而不是具有另一个仅指向值常量之一的“默认”常量。这样，您可以在基类中设置主默认值，如果子类想要选择自己的默认值，它们只需覆盖该方法。

此外，这允许您在 callApi() 的文档块中的 @param 标记中特别提及这些不同的参数选项。

最后，我建议将常量值设置为简单的整数而不是字符串。这样一来，由于值本身不会提供特别丰富的信息，调用者在执行callApi() 时更有可能使用常量名称，从而使他们自己的代码更具可读性并且不太可能传递意外值。