Jump to:
| Project: | API |
| Version: | master |
| Component: | User interface |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (fixed) |
Issue Summary
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.
Comments
#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.
#7
Just as a note, on php.net, most of the examples are provided in comments. We now have the ability on api.drupal.org to add comments, which can have usage examples.
I personally think that it would be better to put the examples in the function headers, perhaps with our own custom @example/@endexample tag.
However, when the idea of adding comments to api.drupal.org was discussed, I suggested that we put examples in the function doc headers and not allowing comments, and I was overruled in favor of using comments. And one thing in comments' favor: they would allow various people to put in multiple examples...
So maybe this issue is fixed?
#8
#9
IMO a decent example for each actual API is something that should be done, and required by committers.
#10
The question is where to provide those examples:
- Examples for Developers project
- Handbook page about the API
- docblocks
IMO, the first two make more sense (preferably integrated together), if you are talking about examples that span "how to use an API".
If you are talking about examples of how to use a particular function, then we can probably do it in the "functions that call this one" section.
Regarding #1, assuming that we also provide a link to the calling function, I don't think we want to clutter up the function page with multiple lines from each calling function. How about something like this:
Functions that call foo()
#11
And by the way, on #5, I think that @example is indicating to read in an example file... so if we add a tag to use for examples, we shouldn't use @example for this purpose.
But I'm not sure why we need an example tag. We can already add examples to function headers using @code, and there are quite a few docblocks that have them [although I have met with resistance when suggesting we expand function header doc in this way, in favor of allowing users to comment. (see above)].
Also, if we know of a particularly great example of how to use a function, we can always say:
See function foo() for an example of how to use this.
in the doc block.
#12
I agree that a whole API example belongs in Examples module - it won't fit.
A simple example of a function, as you point out, can and should go in the function's phpdoc as an @code section. That's what I was really trying to say.
Since Examples module is now in api.drupal.org, its examples can be mentioned in phpdoc, which is cool.
#13
So, I don't think we need any modifications of the API module for this to happen?
#14
Automatically closed -- issue fixed for 2 weeks with no activity.