Support of @verbatim tags
neochief - June 1, 2008 - 17:11
| Project: | API |
| Version: | 5.x-1.x-dev |
| Component: | Code |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | needs work |
Description
I've prepared patch for @verbatim tags support. It's much like @code processor, but isn't adds >?php to the block.
| Attachment | Size |
|---|---|
| varbatim_tags.patch | 1.17 KB |
#1
#2
I can understand what the patch does, but I'm not sure what the correct behavior is here.
According to the doxygen documentation (for example here [1]), the @verbatim tag simply disable all commands, while the content of the @code tag are interpreted as C/C++ (in our case PHP) code.
Thus, it looks like @verbatim tags will require special handling (they need to be interpreted as early as possible and there code contents should be escaped).
[1] http://www.stack.nl/~dimitri/doxygen/commands.html#cmdverbatim
#3
Yes, I've already seen that doc before. In our case verbatim must formats like a simle HTML code, so I thought it would be nice to put our usual php pritifying on it. Results of it's work you can see here
To be honest, the code is changed a little to get this result. The main problem was in P tags generation, that is making the HTML non-valid. So I played with line breaks to make a right result.
#4
#5
see also : #286652: @verbatim marker not getting handled properly
#6
I agree with Damien Tournoud, if we implement @verbatim, it should do what other documentation parsers do.
I think our @code is a bit chatty, prefixing everything with <?php.
#7
Doing some docs at the moment, code that isn't PHP. I don't know whether to use @code (and have misleading php tags) or use @verbatim and accept it will look broken for a while.
Is there simply a way to force a line break in docs? I don't see it looking in the api module code, but then I'm not crash hot at reading code that's full of regular expressions...