/**
* 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;
}
public static String computeDocumentation(
FunctionDocumentation documentation, IDocument document, String name) {
String additionalInfo = Messages.PHPDocUtils_noAvailableDocs;
StringBuilder bld = new StringBuilder();
bld.append("<b>" + name + "</b><br>"); // $NON-NLS-1$ //$NON-NLS-2$
if (documentation != null) {
String longDescription = documentation.getDescription();
longDescription = longDescription.replaceAll("\r\n", "<br>"); // $NON-NLS-1$ //$NON-NLS-2$
longDescription = longDescription.replaceAll("\r", "<br>"); // $NON-NLS-1$ //$NON-NLS-2$
longDescription = longDescription.replaceAll("\n", "<br>"); // $NON-NLS-1$ //$NON-NLS-2$
if (longDescription.length() > 0) {
bld.append(longDescription);
bld.append("<br>"); // $NON-NLS-1$
}
TypedDescription[] tagsAsArray = documentation.getParams();
// buf.append("<br>"); //$NON-NLS-1$
for (int a = 0; a < tagsAsArray.length; a++) {
bld.append("<br>"); // $NON-NLS-1$
bld.append("@<b>"); // $NON-NLS-1$
bld.append("param "); // $NON-NLS-1$
// buf.append();
bld.append("</b>"); // $NON-NLS-1$
bld.append(tagsAsArray[a].getName());
bld.append(' ');
for (String s : tagsAsArray[a].getTypes()) {
bld.append(s);
bld.append(' ');
}
bld.append(' ');
bld.append(ContentAssistUtils.truncateLineIfNeeded(tagsAsArray[a].getDescription()));
}
} else {
bld.append(additionalInfo);
}
if (documentation != null) {
TypedDescription return1 = documentation.getReturn();
if (return1 != null) {
String[] types = return1.getTypes();
if (types.length > 0) {
bld.append("<br>"); // $NON-NLS-1$
bld.append("@<b>return </b>"); // $NON-NLS-1$
bld.append(ContentAssistUtils.truncateLineIfNeeded(return1.getDescription()));
StringBuilder typesBuilder = new StringBuilder();
for (int a = 0; a < types.length; a++) {
typesBuilder.append(types[a]);
typesBuilder.append(' ');
}
bld.append(ContentAssistUtils.truncateLineIfNeeded(typesBuilder.toString()));
}
}
List<TypedDescription> vars = documentation.getVars();
if (vars != null) {
for (TypedDescription var : vars) {
if (var != null) {
String[] types = var.getTypes();
if (types.length > 0) {
bld.append("<br>"); // $NON-NLS-1$
bld.append("<b>"); // $NON-NLS-1$
bld.append(Messages.PHPDocUtils_documentedType);
bld.append("</b>"); // $NON-NLS-1$
bld.append(var.getDescription());
for (int a = 0; a < types.length; a++) {
bld.append(types[a]);
bld.append(' ');
}
}
}
}
}
}
// Specifically look for HTML 'input' tags and change their open and close chars. The HTML
// rendering does
// not
// remove them when the hover is rendered, introducing form inputs in the hover popup.
// @See https://aptana.lighthouseapp.com/projects/35272/tickets/1653
Matcher inputMatcher = INPUT_TAG_PATTERN.matcher(bld.toString());
int addedOffset = 0;
while (inputMatcher.find()) {
int start = inputMatcher.start();
int end = inputMatcher.end();
bld.replace(start + addedOffset, start + addedOffset + 1, "<"); // $NON-NLS-1$
addedOffset += 2;
bld.replace(end + addedOffset, end + addedOffset + 1, ">"); // $NON-NLS-1$
addedOffset += 4;
}
additionalInfo = bld.toString();
return additionalInfo;
}
/**
* 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;
}