I was not able to reference a specific class method using the doxygen #see command.
Suppose I have a class Server with a method start like below
#interface Server : NSObject
- (void) start:(NSInteger) mask;
#end
And suppose I have another class that has an object of Server.
#interface RandomNumberGeneration
/// How can I reference the method start from
/// class server using the command #see
/// #see ????
+ (NSInteger) generate;
#end
So, is there a way to reference the method start of class Server?
Copied from here
#see text | URL | classname | classname#methodname Use this to tag to
refer the reader to some other source of related information.
So I guess it should be:
/// #see Server#start:
See the doxygen manual page Automatic link generation for more information on referencing classes and functions. In particular see the section "Links to Functions".
Typically, I use the function refernce pattern
<className>::<functionName>
So in your case, I would use
/// \see Server::start
However, from the doxygen manual
For JavaDoc compatibility a # may be used instead of a :: in the patterns above
as stated in #PeterG.'s answer.
For completeness, note that if you a reference a member in the same class
In the documentation of a class containing a member foo, a reference to a global variable is made using ::foo, whereas #foo will link to the member.
Related
The MSDN article on #If Then #Else (https://msdn.microsoft.com/en-us/library/tx6yas69.aspx) gives me the basics on conditionally compiling conditional statements.
I happen to have longer lists of declarations that must be initialized differently, based upon multiple platforms. Am I required to use #ElseIf at compile time, or is there a #Select Case option too?
No there are no #Select Case directives in VB .Net (as pointed out by Icepickle)
According to Conditional Compilation, you can define compilation constants #Const and test them to include or exclude blocks of code.
If you have a lot of different architectures/platforms, maybe it is better to write a different file for each platform, and protect the file with the constant check
First you declare an interface so the rest of your code will always be able to find what it needs :
Public Interface IPlatformDependant
Property Test1 As Integer
'Define here all the parameters used by your application
End Interface
File platform1.vb :
#If Platform = 1
'The code for the first platform
Public Class PlatformDependant
Implements IPlatformDependant
Public Property Test1 As Integer Implements IPlatformDependant.Test1
End Class
#End If
File platform2.vb :
#If Platform = 2
'The code for the second platform
Public Class PlatformDependant
Implements IPlatformDependant
Public Property Test1 As Integer Implements IPlatformDependant.Test1
End Class
#End If
In your project designer, you define platform to which you want, and only one class PlatformDependant will be used at a time. The classname can even stay the same...
The Interface here is optional, but it makes you sure that all your classes implements the required method.
I'd like to add verbose information about my core classes without embedding it all above those classes in the source file.
For instance, I'd like to create a separate file with voluminous info about class Foo, probably in markdown or html. Then when I view class Foo in the doxygen-created output, I'd like the class page for Foo to contain all my voluminous and beautifully marked up documentation in its details section along with any other comments I did put above class Foo.
Is this possible?
If you currently have a file Foo.h
/**
A short description of class Foo.
*/
class Foo
{
}
You can add additional documentation in a file with a .dox extension (let's call it Foo.dox)
/**
More details about Foo.
Maybe you only want to distribute this to your nicer customers.
#class Foo Foo.h
*/
Don't forget to add the .dox file to the INPUT line of your configuration file
INPUT = \
Foo.h Foo.dox
Trying to go through my project and expand documentation, and have the following situation:
//TestClass.h
namespace Test {
public enum class TypeOne {
/// <summary>
/// Description <see cref="Test::TypeTwo">TypeTwo</see>
/// </summary>
AAA
};
public enum class TypeTwo {
BBB
};
}
cref produces following error:
warning C4638: XML document comment applied to 'Test.TypeOne.AAA': reference to unknown symbol 'Test::TypeTwo'.
Is there anyway to get the xml documentation to recognize TypeTwo? I would just put TypeTwo above TypeOne, but TypeTwo also as a cref to TypeOne so I would be back in the same situation.
Am I just being stupid?
You'll probably need to handle this situation like you would regularly for such a circular reference in C++: Forward declare TypeTwo before TypeOne (but don't define it).
I think XML documentation may use C#'s scoping notation (the error message certainly does) regardless of the source file language, so perhaps try Test.TypeTwo.
I have an enum in my .h file like so:
/** \memberof MyClass
Values for keypress bitmasks for #method and MyClassDelegate#otherMethod */
enum MY_KEYS {
MY_KEY_1_DOWN, /**< KEY 1 press */
MY_KEY_1_UP, /**< KEY 1 release */
MY_KEY_2_DOWN, /**< KEY 2 press */
MY_KEY_2_UP, /**< KEY 2 release */
};
Doxygen generates an entry for this enum under "Public Types" as well as "Member Enumeration Documentation" where the detailed descriptions show up. However, it generates no documentation for the members of the enumeration. I want to list the members of my enumerations and comment them, so that my users can know which values to use where they formal type of an argument is this enumeration.
Don't know if it's relevant--this is in Objective-C, hence \memberof MyClass to show up on this class's page.
Not sure why doxygen doesn't see enum values as inherited by the \memberof command. It doesn't work if you manually set the individual values as members of the enum or class either.
Anyway, the workaround is that if you want the enum to actually appear inside the class, you need to define it within the class interface:
#interface MyClass : NSobject
/**
Values for keypress bitmasks for #method and MyClassDelegate#otherMethod
*/
enum MY_KEYS {
MY_KEY_1_DOWN, /**< KEY 1 press */
MY_KEY_1_UP, /**< KEY 1 release */
MY_KEY_2_DOWN, /**< KEY 2 press */
MY_KEY_2_UP, /**< KEY 2 release */
};
#end
This actually makes more sense IMO, as there's no guarantee that header files contain related types - it's just expected of good design.
I stumbled over the same problem (although for a pure C documentation) - unfortunately this seems to be an issue with Doxygen, see the corresponding Bugzilla entry
individual values in enum not documented if the enum is a member of a
C class
https://bugzilla.gnome.org/show_bug.cgi?id=762320
or the older related bug:
When #relatesalso is used, Doxygen does not output members of enum.
https://bugzilla.gnome.org/show_bug.cgi?id=609299
Update:
A quick fix which solves this problem (tested in Doxygen 1.8.11):
Edit src/doxygen.cpp and remove (or comment) line 7375 in function addEnumValuesToEnums:
if (!e->name().isEmpty() && (fmn=(*emnsd)[e->name()]))
// get list of members with the same name as the field
{
MemberNameIterator fmni(*fmn);
MemberDef *fmd;
for (fmni.toFirst(); (fmd=fmni.current()) ; ++fmni)
{
/* REMOVED LINE 7375: if (fmd->isEnumValue() && fmd->getOuterScope()==md->getOuterScope()) // in same scope */
{
//printf("found enum value with same name %s in scope %s\n",
// fmd->name().data(),fmd->getOuterScope()->name().data());
if (nd && !nd->name().isEmpty() && nd->name().at(0)!='#')
{
The "outer scope" of the C enum was still set to global, i.e. the block which adds enum member values had not been reached.
Please note that I made just a short check and did not thoroughly test the fix - it might have side-effects....
I have two c++/cli dlls (i.e. compiled with /clr) where A.dll references B.dll. In assembly B, I have a method, GetMgdClassB, I'd like to call from assembly A. Here is the code in assembly B (B.cpp):
namespace B
{
public class NativeClassB
{
public:
NativeClassB();
// ...
};
public ref class MgdClassB
{
public:
static MgdClassB ^ GetMgdClassB(const std::vector<NativeClassB *> & vecNativeBs)
{
// ...
vecNativeBs;
return gcnew MgdClassB();
}
};
}
Notice that the method GetMgdClassB takes a std::vector. In assembly A, I attempt to call this method with the following code (A.cpp):
namespace B
{
class NativeClassB;
}
#pragma make_public(std::vector<B::NativeClassB *>)
namespace A
{
void Foo()
{
std::vector<B::NativeClassB *> vecNativeBs;
B::MgdClassB::GetMgdClassB(vecNativeBs);
}
}
When I compile A.cpp, I get the following error:
error C2158: 'std::vector<_Ty>' : #pragma make_public directive is currently supported for native non-template types only
the reason I wanted to add this pragma is because native types are private to the assembly by default. If I remove the pragma I get the following error (as expected):
error C3767: 'B::MgdClassB::GetMgdClassB': candidate function(s) not accessible
since the template instantiation type std::vector<B::NativeClassB *> is private to the assembly.
Attempted Solutions
1. Use void *, break type safety:
Change the method, GetMgdClassB to take a void * and pass the address of the std::vector<NativeClassB *> to the method. In GetMgdClassB. I can then static_cast the passed in void * to std::vector<NativeClassB *> *. This, of course, works, but breaks type safety.
2. Create a Managed wrapper for NativeClassB, pass a managed container
Create a managed class, say ref class NativeClassBWrapper who's sole purpose is to hang on to a reference to the native NativeClassB. Change GetMgdClassB to take a managed container of NativeClassBWrappers (e.g. List<NativeClassBWrapper ^> ^). This has the downside of having to create and populate a new managed container prior to calling GetMgdClassB, and then within managed class B, I have to repackage it into the the native container std::vector<NativeClassB *> (since the code in B deals with this type.
Currently, I'm leaning toward going with Solution #1, since (a) it doesn't introduce any performance concerns and (b) I'll only be doing this in a few cases. I don't like losing the type safety, but it seems justifiable given the current deficiency in the compiler's ability to make native template instantiation types visible.
Question:
Are there better work arounds?
Related Question:
C++ CLI error C3767: candidate function(s) not accessible
I'm not aware of any way to export that type. If you have to have that function signature, I would lean in the direction of using a mix of managed and native exports (managed functions using native types can't be consumed by other languages anyway), and maybe use delay loading when calling the native exports so you have a chance to trap errors finding the assembly in the usual .NET way.
But your particular function may be problematic since it uses both managed types and complex native types in the signature.
In general, the best practice is to not pass native C++ classes across DLL boundaries at all, since this sets you up for One Definition Rule violations.
For this particular situation, my suggestion is to make an wrapper that implements ICollection. That cures the problem just like your solution #2, without ever having to actually copy all the elements into a new data structure.
I received a solution from Mike Danes on another forum:
http://social.msdn.microsoft.com/Forums/en-US/vclanguage/thread/b43cca63-b0bf-451e-b8fe-74e9c618b8c4/
Basically, the solution is to create a native wrapper (call it VectorOfNativeB) in assembly B that holds on to a pointer or reference to the std::vector. Export VectorOfNativeB and make it publicly visible. Change method GetMgdClassB to take a pointer or reference VectorOfNativeB.
[posted this here for future reference and to see if anyone here has any comments about this solution].