I am just wondering which one is the format I have to write comments in functions so they display when hovering over the function with the mouse.
something like
void myfunct(int a; char b, float c);
This function just messes with the variables with no objective
but to show people from stack overflow what I mean.
Inputs-> a: does nothing
b: neither this one
c: nope
So when I use the functions in a big project I don't need to go looking for what was that specific function for or what was that variable's meaning.
if you think of something like C# or VB that show description of parameters and function, there is no such thing in MSVC, but Microsoft have an special format for code comments as follow that you can use for generating help:
/// <summary>
/// summary of variable, function, class or any thing else
/// </summary>
/// <remarks>
/// detailed description of object
/// </remarks>
/// <param name="a">description of a</param>
/// <param name="b">description of b</param>
/// <param name="c">description of c</param>
/// <returns>describe return value of function</returns>
when you compile your code it will generate an XML document that can be used to generate help documents.
Related
I'm new and getting into programming so I apologize if this has already been answered or explained. Basically, I've been looking in the documentation of the SFML library and come across some sf::Font class public member functions. One for example is this:
bool sf::Font::loadFromFile ( const std::string & filename )
Following that is what the function does:
/// \brief Load the font from a file
///
/// The supported font formats are: TrueType, Type 1, CFF,
/// OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.
/// Note that this function know nothing about the standard
/// fonts installed on the user's system, thus you can't
/// load them directly.
///
/// \warning SFML cannot preload all the font data in this
/// function, so the file has to remain accessible until
/// the sf::Font object loads a new font or is destroyed.
///
/// \param filename Path of the font file to load
///
/// \return True if loading succeeded, false if it failed
///
/// \see loadFromMemory, loadFromStream
///
I've downloaded the library and looked inside the header files but I can't seem to find how the loadFromFile function actually accomplishes the loading (In other words, I'd be looking for a function body or a function definition that does the work). The documentation only explains what the function does, not how.
I'm sorry if this is a stupid question or something that should be apparent. I'm just extremely curious about where the core of the function is.
By the way, here is an exact link to the page and section of the documentation I'm referring to.
Thank you to anyone who answers.
The method you are looking for can be found in the public Github repository.
It's in the file Font.cpp starting on line 122:
https://github.com/SFML/SFML/blob/master/src/SFML/Graphics/Font.cpp#L122
Documentation will not mention this because the documentation is about the behavior the user of this function can rely on. How a method achieves this behavior is a private implementation detail that the user should not need to know.
In C# i just type "///" and it creates nice comment block with information partially there.
Is there any way to do the same for C++ code?
Maybe plugin?
This is just example
/// <summary>
/// Description for SomeMethod.</summary>
/// <param name="s"> Parameter description for s goes here</param>
/// <seealso cref="String">
/// You can use the cref attribute on any tag to reference a type or member
/// and the compiler will check that the reference exists. </seealso>
public void SomeMethod(string s)
{
}
Try Visual Assist. More info in this question.
I am using the vim plugin DoxygenToolkit that is pretty cool.
by highlighting a function and calling :Dox it setup a doxygen comment like below.
/// #brief
///
/// #param id
///
/// #return
int32_t printme(int32_t it)
Is there any setting in this tool that prevent to prepare only the #brief section without showing the #return and #param ones?
I tried by setting thse 2 parameters, but I cam see that the argument of the function is still printed out together with many lines.
let g:DoxygenToolkit_paramTag_pre=""
let g:DoxygenToolkit_returnTag=""
/// #brief
///
/// id
///
///
int32_t printme(int32_t it)
I know this is not the plugin you are using, but anyway, with lh-cpp (:DOX command), you would be able to override the doxygen-function snippet and keep/remove/change whatever you wish. The plugin takes care of detecting everything that can be detected, the snippet formats them.
Today I decided it was a good idea to start documenting my functions with the intellisense thing.
The problem is, when I type /// and press enter it doesn't create the tags to fill in (shouldn't it?).
And worse, even if I document my function manually:
/// <summary>
/// Gets something.
/// </summary>
/// <param name="somethingElse"> Something else.</param>
/// <returns> Something. </returns>
int getSomething(int somethingElse);
When I go and write "object.getSomething(" it only shows me the parameter, like if the documentation never existed.
Yes, I set it to generate XML documentation files in project options -> configuration properties -> c/c++ -> output and tried to rebuild the project.
No effect.
Any ideas?
In my years at college I've learned to program Java, which I did in Eclipse. I loved the feature in Eclipse on how Javadoc comments were able to pop-up in a window. At the moment I'm programming C++ and I'm really starting to miss this feature.
That's why I'm asking: is there a plug-in of something that acchieves the same result. Currently I am programming c++ with Visual Studio Express 2010, that does not have anything like this except for showing a function interface in the auto completion window. I would like to read more info such as reading up on pre- and postconditions for example, either for code from existing libraries (if they exist) or otherwise only for code I wrote myself.
Now I know of Doxygen, but that it not really what I'm looking for. It is a good enough fall back mechanism, but I really like to have it readily available from the same window I'm writing my code in.
Does something like this exist for Visual Studio? Or can I start using the C++ version of Eclipse and run the Javadoc generator there (I actually haven't tried this!) to get those nice pop-up comments?
EDIT:
I've been trying to get XML style comments working, but something like:
/// <summary>This constructor takes parameters to set the
/// members of the Cow class.
/// <param name="ho">Hobby as string of the cow.</param>
/// <param name="wt">Weight of the cow as a double.</param>
/// </summary>
Cow(const char * nm, double wt);
still only gives me the string "Cow(const char * nm, double wt)" in the pop-up window. Built with the \doc option, I do have a .xml file generated (in my Debug folder).
In C# you can write
///
And it will generate a XML style comment like:
/// <summary>
///
/// </summary>
/// <param name="parameter"> </param>
/// <returns> </returns>
You can let Visual Studio generate an XML file, which can be processed to get something like javadoc. I'm 100% sure it works on C#, but it seems that C++ uses a different style. If I go to project options > Configuration Options > XML Document Generator > General, and set the "Validate IntelliSense" to Yes, you can place comments in your .h file:
class Test {
public:
// The constructor
Test(void);
// The destructor
~Test(void);
// The function description
void Function();
};
If I go to my main.cpp, and type this:
Test * test = new Test();
test->
As soon as I hit the '>', a box pops up with a list of functions (destructor and the function in this case). If I select Function for example, a tooltip pops up with "The function description":
void Test::Function();
The function description
File: test.h
I'm not sure if there are any plugins, but I hope I helped you a bit here!
If you have CodeRush/Refactor you can try the CR_Documenter plugin (use VS Extension Manager). It provides a new dockable window with such documentation.
I am with you - Eclipse is so much better for viewing documentation.
Use SandCastle to integrate with the builtin help (F1). Its not as good as inline help like you get in Eclipse, but you can hover over a type, press F1 and then you are there.
To do this, install Sandcastle and Sandcastle Help File Builder. Then in your Sandcastle Help File Builder project, make sure to tick the box for MSHelpViewer. This will generate documentation and a script you can run to integrate your custom documentation into the F1 help.