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.

Bug 169660 - Folded comments should show first line (esp. PHPDoc)
Summary: Folded comments should show first line (esp. PHPDoc)
Status: RESOLVED FIXED
Alias: None
Product: editor
Classification: Unclassified
Component: Code folding (show other bugs)
Version: 6.x
Hardware: All All
: P3 blocker with 4 votes (vote)
Assignee: Svata Dedic
URL:
Keywords:
: 157469 (view as bug list)
Depends on: 226413
Blocks: 216456
  Show dependency tree
 
Reported: 2009-07-31 18:26 UTC by jeremyclarke
Modified: 2013-03-14 02:07 UTC (History)
4 users (show)

See Also:
Issue Type: ENHANCEMENT
Exception Reporter:


Attachments
Folding of javadoc - proposed ui (24.93 KB, image/jpeg)
2012-10-02 21:49 UTC, markiewb
Details

Note You need to log in before you can comment on or make changes to this bug.
Description jeremyclarke 2009-07-31 18:26:00 UTC
When you fold everything, comments get folded as well, at least in PHPDoc format (the standard way of defining functions
etc for documentation and the way that NetBeans understands your functions). Folded comments don't give any information
and are wasting space. A folded comment should show the first line of the comment in full instead. 

A folded PHPDoc comment currently looks like this:

   [+] /** [...]

IMHO this is not a useful way to present the folded information. By contrast a folded function gives much more info and
looks like this:

   [+] function gv_generate_backbone($arg1, $arg2) [...]

In both cases the folded element requires 1 line of space and has the [+] and [...] buttons to unfold it if desired. 

However, unlike the function the comment completely wastes its space by showing only the fact that its a comment and not
any hints at the contents. We would all be batshit crazy if we thought that folded functions should be listed as 

   [+] function [...]

But effectively that's what we're doing with PHPDoc comments. 

I propose that folded comments allow the first line of text to be displayed. In the case of PHPDoc comment blocks this
would mean showing the textual description of what the function generally does, and would make it a lot easier to scan a
folded document (i.e. 'fold all') and understand what's available. 

I think this idea is almost 100% better than the current system. Showing at least some of the first line of
documentation is much more useful than showing nothing and would make the code folding a lot more valuable. 

If you don't want to completely change the behavior then a setting should be added to do comment folding in this way. 

Is there any explantion/defense for the way it works currently? Maybe some people prefer that completely folded code
look more 'clean', but it really seems like more people would rather get a hint at the contents of their docs than to
have just [...] which they have to carefully click. 

This was brought up on the NetBeans PHP blog awhile ago: http://blogs.sun.com/netbeansphp/entry/code_folding_in_php_editor

The PHP maintainers said it was an issue for 'editor people' so I've labeled this ticket as 'editor->code folding', if
its a PHP thing you can edit it but hopefully it can be considered by whoever can make it happen :)

OTHER CONSIDERATIONS
 * There's no way to say "fold all functions but leave documentation open". I love the 'fold all' and 'unfold all'
keyboard shortcuts, but i really want to see at least some of the docs for it to be useful. 
 * It would solve ticket 157469, where the reporter wants to see what's inside a comment block to ensure that folding is
working correctly. 
 * It would solved ticket 38964 where the reporter wants single-line comments to not be folded. (well maybe you can just
do both at the same time).
Comment 1 Svata Dedic 2012-02-10 15:43:19 UTC
Adding Dusan, might be also interesting for Java/Javadoc comments - show the summary sentence.
Comment 2 Svata Dedic 2012-05-28 14:59:00 UTC
*** Bug 157469 has been marked as a duplicate of this bug. ***
Comment 3 markiewb 2012-10-02 21:49:18 UTC
Created attachment 125257 [details]
Folding of javadoc - proposed ui
Comment 4 markiewb 2012-10-02 21:51:14 UTC
(In reply to comment #1)
> Adding Dusan, might be also interesting for Java/Javadoc comments - show the
> summary sentence.

+1 That would be very useful. Intellij Idea does this already? 
I added a screenshot of the proposed visuals for javadoc.
Comment 5 Svata Dedic 2013-03-12 15:44:20 UTC
Will be integrated as http://hg.netbeans.org/jet-main/rev/7b5fdc1dbdaa
Comment 6 Quality Engineering 2013-03-14 02:07:33 UTC
Integrated into 'main-golden', will be available in build *201303132300* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main-golden/rev/7b5fdc1dbdaa
User: Svata Dedic <sdedic@netbeans.org>
Log: #169660: Implemented 1st line of phpdoc preview in fold placeholder