| Author |
 Topic  |
|
|
MrDoomMaster
Tomato Guru
251 Posts |
 Posted - Jan 03 2008 : 11:15:56 AM
|
Hi,
When you hover your mouse over a variable, for example, a quickinfo tooltip will pop up showing you the definition information for the variable and, if the option is enabled in VAX, it will also show you surrounding comment blocks.
Assume the following code:
/// Represents various behavioral properties for the Camera.
struct CameraBehavior
{
float initialVelocity, ///< Units of movement per second a key/button is held down.
accelPerSecond, ///< Acceleration added each second a directional key is held down.
accelModifier, ///< Amount to add/subtract to/from AccelerationPerSecond above when
///< the CameraAction::INCREASE_ACCEL and CameraAction::DECREASE_ACCEL
///< actions occur.
accelIdleTime, ///< Seconds to wait (after all movement actions end) before velocity
///< is reset to initial velocity.
rotationPerPixel, ///< Amount of rotation, in degrees, to apply to the camera per pixel
///< of cursor motion. Used for cursor motion input only.
rotationPerSecond; ///< Amount of rotation, in degrees, to apply to the camera per second.
///< Used for key/button input only.
};
I've used doxygen comment formatting to document this structure and each one of its members.
Notice how I extend the single-line comments for some of the members to multiple lines, which is valid in doxygen. However, for the multi-line documentations above, only the first line shows up in the quickinfo tooltips when I hover over the variables. For example, if I hover over "accelIdleTime", the tooltip shows: "Seconds to wait (after all movement actions end) before velocity" instead of "Seconds to wait (after all movement actions end) before velocity is reset to initial velocity."
I'm not sure if the IDE is doing this or if VAX is. In any case, I think it would be great if you guys could extend the tooltips to support multiline comments like above.
Thanks. |
Edited by - MrDoomMaster on Jan 03 2008 11:20:01 AM |
|
|
feline
Whole Tomato Software
United Kingdom
18943 Posts |
Posted - Jan 04 2008 : 3:27:51 PM
|
What happens with the code:
struct commentsAboveAndAfter
{
int nWeight; // this is the weight of an item
// now comes the dimensions of the item, in 3 dimensions:
int nHeight, nDepth, nWidth; // note this is done in millimetres
};
In your example, as a person looking at it, it is fairly clear what is happening. However this is simply one of several different ways or placing / organising comments, and what is going on is much less clear to a computer. |
zen is the art of being at one with the two'ness |
 |
|
|
MrDoomMaster
Tomato Guru
251 Posts |
Posted - Jan 04 2008 : 3:30:33 PM
|
quote:
Originally posted by feline
What happens with the code:
struct commentsAboveAndAfter
{
int nWeight; // this is the weight of an item
// now comes the dimensions of the item, in 3 dimensions:
int nHeight, nDepth, nWidth; // note this is done in millimetres
};
In your example, as a person looking at it, it is fairly clear what is happening. However this is simply one of several different ways or placing / organising comments, and what is going on is much less clear to a computer.
Good point. Your point is obvious and I should have foreseen that whitespace, yet again, would be an issue. Fortunately for me, this isn't a big issue. I can live without it. Besides, if I need proper documentation I visit the Doxygen HTML output anyway or go directly to the source, I don't normally depend on the tooltips.
Thanks Feline! Hope you had a great holiday! |
|
|
|
feline
Whole Tomato Software
United Kingdom
18943 Posts |
Posted - Jan 07 2008 : 3:09:59 PM
|
I half remember a similar discussion shortly after I started using VA, and we ran into the same problem of white space, or "strangely" positioned comments. Plus, after all the practice, I am getting better at spotting ways of breaking things 
It was a very nice holiday, thank you Lots of relaxation and presents, and other good things |
zen is the art of being at one with the two'ness |
|
|
|
MrDoomMaster
Tomato Guru
251 Posts |
Posted - Jan 07 2008 : 3:13:56 PM
|
You could do something completely insane and have VAX parse doxygen comment formatting. This way, whitespace can be ignored as the comments have special meaning that combines them :)
But I'm being unrealistic now. You guys have enough on your plates. |
|
|
|
feline
Whole Tomato Software
United Kingdom
18943 Posts |
Posted - Jan 08 2008 : 09:22:57 AM
|
The idea has come up before, but you then run into all the different flags Doxygen supports, plus, why single out Doxygen? People will be asking for support for their own custom comment formats as well.
We don't have any plans to try anything like this. |
zen is the art of being at one with the two'ness |
|
|
| |
Topic |
|
|
|
Comments in tooltips
