Show example code on references tab.
| Project: | API |
| Version: | HEAD |
| Component: | User interface |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | active |
Jump to:
Right now if I look at the reference tab for a function, let's say, l, I'm shown a list of functions that call l(), along with a description of what those functions do. This is not really helpful.
What would be way more helpful is if the "Location" and "Description" columns were replaced with a column that showed me an actual line from the referenced function where the function was used. For example, for aggregator_block, it would show:
$read_more = '<div class="more-link">'. l(t('more'), 'aggregator/sources/'. $feed->fid, array('title' => t("View this feed's recent news."))) .'</div>'; Probably some totally arbitrary logic could be used like "find the first instance of this function in the function and just print that line."
This would make api.drupal.org function similarly to PHP.net by showing actual usage examples of the function, but even better as they'd all be "real life" usage examples from core.
#1
Great idea. But IMHO context is important. Maybe not for simple functions like l() or t(), but for most others it's important when and where a function is and should be called.
So retrieving just the line of the first occurence seems to be not enough. So the next question arises: How much of the calling code is necessary to get an idea of the context a function is used in?
Instead of storing a copy of the code in the database we should find a way to fetch actual file contents directly from the documented file. A workable solution might be to read all lines of a file separately using
fgets($file, 0)until we reach the lines we want to process, followed byfgets($file, 512)until we reach the end of the code we want to output. That content can be filtered and processed to markup afterwards (using built-in php highlighting, GeSHi, aso.).#2
I think it would be best to store a predefined piece of example code in the database. Looking in files for existing pieces of code might not result in a usable example.
#3
That's not a bad idea at all, and would certainly be easier to parse.
Does Doxygen natively support some syntax like @example?
#4
#5
The doxygen precedent defines some cumbersome-looking @tags:
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdexample
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdinclude
http://www.stack.nl/~dimitri/doxygen/commands.html#cmddontinclude
I'm not sure these are a good idea, but they exist and we could implement them.
#6
As a newish developer this is one thing that I really miss that I can find in the php docs. I think using a separate example would be more helpful as you can explain the code in context of the current method. Whereas when it's using actual core code figuring out that context becomes really difficult.