This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
Created attachment 124184 [details] Shows the inconsistent left margin applied to 'Throws', 'Author', and 'Last Modified By' compared to 'Parameters' and 'Returns' Please see the attachment to clearly understand the descriptions below. The formatting of the 'Throws', 'Author', and 'Last Modified By' subheaders has more left margin compared to the 'Parameters' and the 'Returns' subheaders. They all should have the same amount of left margin. The APIGen code to produce the documentation shown on the attachment is written below: /** * This function sends an email. * * @param array $pFrom From whom the email came from. * This parameter <b>can contain 1 EMAIL ADDRESS only.</b> <br/> * <b>Example:</b> * <code> * $From = array("Name" => "Kobe Bryant","EmailAddr" => "kbryant@nba.com"); * </code> * * @param array $pTo To who the email would be sent to. * This parameter <b>can contain 1 OR MORE EMAIL ADDRESS.</b> <br/> * <b>Example:</b> * <code> * $To = array(array("Name" => "Dwight Howard","EmailAddr" => "dhoward@nba.com"), * array("Name" => "Steve Nash","EmailAddr" => "snash@nba.com"),); * </code> * * @param string $pSubject The title of the email. <br/> * <b>Example:</b> * <code> * $Subject = "Title of Email"; * </code> * * @param string $pMsg The contents of the email. * This can be <b>set to TEXT OR HTML CONTENT.</b> <br/> * <b>Example:</b> * <code> * $Msg = 'This is a HTML message!<a href=' . $url . '> * <img src="' . $imgLogo . '" alt="Logo" /></a>'; * </code> * * @return boolean returns True if email was sent successfully.<br/> * * <b>Throws:</b> Exception Throws an Exception object. * * <b>Author:</b> FirstName LastName <FLastName@domain.com> on 7/31/2012 * * <b>Last Modified By:</b> FirstName LastName <FLastName@domain.com> on 8/5/2012 */
Editor area. Thanks for reporting.
Everything is correct, because you don't use a proper annotations. You shoud use @author annotation instead of <b>Author</b> text...and such. If you use just simple text as you used, it's aligned to the right, description, side.
Created attachment 124277 [details] Incorrectly displays the formatting with @author tag used.
(In reply to comment #2) > Everything is correct, because you don't use a proper annotations. You shoud > use @author annotation instead of <b>Author</b> text...and such. If you use > just simple text as you used, it's aligned to the right, description, side. I tried using proper annotations before. It does not work too. For simplification sake, I removed all @params except one. See code shown below. /** * This function sends an email. * * @param array $pFrom From whom the email came from. * This parameter <b>can contain 1 EMAIL ADDRESS only.</b> <br/> * <b>Example:</b> * <code> * $From = array("Name" => "Kobe Bryant","EmailAddr" => "kbryant@nba.com"); * </code> * * @return boolean returns True if email was sent successfully. * * <b>Throws:</b> Exception Throws an Exception object. * * @author FirstName LastName <FLastName@domain.com> on 7/31/2012 * * <b>Last Modified By:</b> FirstName LastName <FLastName@domain.com> on 8/5/2012 */ Please see the attached APIGen documentation output for the documentation code shown above. As you can see from the attached file, incorrect formatting is still shown. I need to have the documentation output to be shown in order as Brief Description Parameters: Returns: Throws: Author: Last Modified By: To us, this is the most logical order and this is what we want to show in our documentation. I tried to find APIGen tags documentation but to no avail (if you happen to have it, please kindly send it to me). From doing search on the internet, I found that I should use the PHPDocumentor's documentation on tags instead. The link is http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html. From there, I found the @param, @return, and @author but no @throws and @modifyBy (or something like this). So I used HTML tags that PHPDocumentor supports. From PHPDocumentor, it shows me I can use the <b></b>, <code></code>, etc. The link is http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html Go to the 'DocBlock Description details' 1/4 down the page. From here, you will see the list of HTML tags phpDocumentor supports. By the way, if you remove 'Throws' and 'Last Modified By', you will see the 'Author' sub-header are all in CAPS and still 1 space not aligned with the 'Parameters:' and 'Returns:' sub-headers.
Created attachment 124453 [details] Annotation rendering NB 7.3 Annotations in DEV build are handled differently. 1) after annotation can't be any other text, so your "<b>Foo:</b>" snippets are not handled correctly. 2) some annotations are handled differently than others (@param, @return and such), becuase these are most important for IDE and user. 3) All other annotations are handled similarly as you can see on a screenshot. 4) Last Modified By annotation is ambiguous since we have VCS (Git, Mercurial and such). If you use PHPDoc differently and doesn't comply these rules, the result can be strange. If you want to have whole PHPDoc parser more flexible, file some new enhancements, but now it works as expected. List of APIGen annotation can be found here: https://github.com/apigen/apigen/issues/62
I'll make an enhancement from this issue and will try to look at it for some later release. It can't be rewritten for 7.3.
I saw your attachment, Annotation rendering NB 7.3. Suggestions: 1) Is it okay to show the @throws and @author as "Throws:" and "Author:" respectively (with the first letter capitalized and a colon)? Also, have them left-aligned with "Parameters:" and "Returns:". They looked to be one space off. These would be consistent with "Parameters:" and "Returns:". 2) Hopefully all Tags mentioned in https://github.com/apigen/apigen/issues/62 would have the same formatting mentioned above. Thanks for all your help!