/**
* Returns the parameter documentation (as a {@link FunctionDocumentation} instance) from a given
* {@link IPHPDocBlock}.
*
* @param block - The block to look at when extracting the parameter documetation.
* @param parameterName
* @return FunctionDocumentation or null.
*/
public static FunctionDocumentation getParameterDocumentation(
IPHPDoc block, String parameterName) {
if (block == null) {
return null;
}
FunctionDocumentation result = new FunctionDocumentation();
IPHPDocTag[] tags = block.getTags();
if (tags != null) {
for (IPHPDocTag tag : tags) {
switch (tag.getTagKind()) {
case PHPDocTag.PARAM:
String value = tag.getValue();
if (value == null) {
continue;
}
String[] parsedTag = parseParamTagValue(value);
// Support two forms of @params docs:
// @param $param1 this is param 1
// @param bool $param2 this is param 2
if (!StringUtil.isEmpty(parsedTag[2]) && parsedTag[2].startsWith(parameterName)
|| !StringUtil.isEmpty(parsedTag[0])
&& parsedTag[0].startsWith(removeDollar(parameterName))) {
result.setDescription('\n' + value);
return result;
}
}
}
}
return null;
}
/**
* Returns the function documentation from a given {@link IPHPDocBlock}.
*
* @param block - The block to convert to a {@link FunctionDocumentation}.
* @return FunctionDocumentation or null.
*/
public static FunctionDocumentation getFunctionDocumentation(IPHPDoc block) {
if (block == null) {
return null;
}
FunctionDocumentation result = new FunctionDocumentation();
StringBuilder docBuilder = new StringBuilder();
docBuilder.append(block.getShortDescription());
String longDescription = block.getLongDescription();
if (!StringUtil.isEmpty(longDescription)) {
docBuilder.append('\n');
docBuilder.append(longDescription);
}
result.setDescription(docBuilder.toString());
IPHPDocTag[] tags = block.getTags();
if (tags != null) {
for (IPHPDocTag tag : tags) {
switch (tag.getTagKind()) {
case PHPDocTag.VAR:
{
String value = tag.getValue();
if (value == null) {
continue;
}
TypedDescription typeDescr = new TypedDescription();
typeDescr.addType(value);
result.addVar(typeDescr);
break;
}
case PHPDocTag.PARAM:
String value = tag.getValue();
if (value == null) {
continue;
}
String[] parsedValue = parseParamTagValue(value);
TypedDescription typeDescr = new TypedDescription();
typeDescr.setName(parsedValue[0]);
if (parsedValue[1] != null) {
typeDescr.addType(parsedValue[1]);
}
if (parsedValue[2] != null) {
typeDescr.setDescription(parsedValue[2]);
}
result.addParam(typeDescr);
break;
case PHPDocTag.RETURN:
String returnTagValue = tag.getValue().trim();
if (returnTagValue == null) {
continue;
}
String[] returnTypes = returnTagValue.split("\\|"); // $NON-NLS-1$
for (String returnType : returnTypes) {
returnTagValue = clean(returnType.trim());
returnTagValue = firstWord(returnTagValue);
result.getReturn().addType(returnTagValue);
}
break;
}
}
}
return result;
}