I’m using Doxygen to document a C++ library. Documentation of enumerations is not nearly as helpful as it might be, and I can’t find anything about controlling the output. The generated output puts an undocumented version of the enumeration at the top of the namespace page in an "Enumerations" section, individual elements of which link to the actual useful documentation, under an Enumeration Type Documentation section. In a real example, there may be many of these undocumented enumerations before the page gets around to the Enumeration Type Documentation section where the useful help documenting the use of each value can be found.
How can I suppress the Enumerations section entirely, while leaving the Enumeration Type Documentation section that actually documents the enumeration values?
The output is generated from this example .h file:
//! \file
#pragma once
//! \brief My main namespace
namespace MyNamespace
{
//! \brief An example enumeration with the useful values documented.
enum class MyExampleEnum
{
UNKNOWN,
FirstValue, //!< This is the useful documentation
SecondValue, //!< This is useful documentation of SecondValue
COUNT,
};
}
Related
In my (chemistry related) project, I'd like to use the words Elementand Sequence for data structures. Will there be a conflict with the same names that are already used in Swift, should I rename them to MyElement and MySequence to be safe?
UPDATE:
I'm editing the question to hopefully make it more clear as was requested. The following quote is from the Generics section of Apple's Swift documentation:
Element defines a placeholder name for “some type Element” to be
provided later on. This future type can be referred to as “Element”
anywhere within the structure’s definition. In this case, Element is
used as a placeholder in three places
So, my question was if I can use the word Element for a structure without conflicting. The same for Sequence which I have seen used as well in sample code - although I cannot find it anymore. The accepted answer below explains this.
Those are not reserved words in Swift. The identifier Element is used as an associated type inside some generic types in the standard library, but you can also use it for your own type if you want, although it might become confusing. The identifier Sequence is not currently used by the standard library.
In C++ (at least as of a decade ago), there was speed advantage in defining the body of a class method in the header file, where the class is defined. No function call overhead was suffered because, in the compilation process, the invocation of such functions was replaced by the code in the body of the function. Subsquently, all source level optimizations (and all optimizations beyond source level) could be brought to bear.
Is there an analogous advantage to putting the body of class methods in the classdef file itself rather than in a separate m-file? I'm speaking specifically about the case where one defines a #myclass/myclass.m, with method m-files in the directory #myclass. The two options I'm considering is to have the code for the body of a method mymethod put into the classdef in #myclass/myclass.m versus being in a separate file #myclass/mymethod.m.
However, an very related auxiliary question would be how those two options compare with having everything defined in a myclass.m file, with no folder #myclass.
Please note that I have previously posted this to usenet
Summarizing the comments as the answer to this question: Using an #classFolder folder containing separate method m-files is faster than having a single m file containing the entireties of the function definitions in the classdef. This is the case even though OOP in general has sped up in 2015b.
I find this a happy answer because I see great value in separating the code implementation of a class's methods from the class definition itself. That's the whole idea of separating interface from implementation. I can look at the classdef and see only a map of the class rather than have those key information elements completely dispersed by the deluge of code that accompanies implementation.
It's just too bad that this doesn't work so well for weakly typed languages. What's listed in the classdef is just member names (properties or methods) with no specification of what class they are. So not as much information as in a strongly typed language. In fact, very little info about what the class, its properties, and its methods really are. Furthermore, there is nothing to ensure that the actual method implementation even complies with the argument list in the classdef. These kind of details helped prevent development errors in a strongly typed language, especially when one's body of classes get large.
I'm trying to author documentation for some C++/CX interfaces as XML comments. The result will be parsed by Doxygen as well as by VC++'s own /doc option.
In the documentation for each interface member, I can use <see cref="..."/> syntax to crossreference members of the same interface, as well as to other types that have been forward declared. But what is the proper syntax for referencing a member of a different interface?
All of my attempts produce compiler warnings:
C4638: XML document comment applied to ...: reference to unknown symbol ...
I've seen this question and its answers, but you can't forward declare members of interface classes, can you? And due to circularity, I cannot always make sure to include the declaration of each referenced interface before the one containing the reference.
If the interface were classes, my understanding is that the XML comments could be put on the implementations of the functions rather than their declarations, but for an interface there isn't any implementations of the members that I could move the XML comments to.
Just a little question here.
I found on Play Framework 2 sources:
private[data] object FormUtils {
...
}
Just wonder what the [data] means? Is it just some fancy syntax to say the object / class belongs to a subfolder?
It means that this class can only be used from package play.api.data and its subpackages. It's close to package-private visibility level in Java, but with two differences:
It's visible from subpackages (there are no subpackages in Java, but in Scala, e.g. play.api.data.foo is considered a part of play.api.data).
You can write, e.g. private[api], and it would be visible from all subpackages of play.api.
This article explains Scala access modifiers in more detail.
I have a Sage class that inherits from SageObject. According to the Python documentation,
User-defined classes have __cmp__()and __hash__() methods by default; with them,
all objects compare unequal (except with themselves) and x.__hash__() returns id(x).
However, my class doesn't do this, despite the fact that it doesn't implement a __hash__ method of its own. Instead, it uses the hash value of its string representation (the one returned by its __str__ method). Is this part of the design of Sage classes, something different from normal Python classes? Is there a hierarchy of places that Sage might look in order to find an acceptable hash value?
Luckily, you practically answered the question yourself. Try the ?? trick to find the source code.
sage: SageObject.__hash__??
Type: wrapper_descriptor
Base Class: <type 'wrapper_descriptor'>
String Form: <slot wrapper '__hash__' of 'sage.structure.sage_object.SageObject' objects>
Namespace: Interactive
Definition: SageObject.__hash__(self)
Source:
def __hash__(self):
return hash(self.__repr__())
So yes, it's intentional for most of these things. If you wanted to implement something different for hashes, I guess you could. It would be worth asking on one of the Sage lists if this was code you were interested in contributing and thought it might conflict with something.