I am using doxygen 1.8.9.1 and bibtex to generate the reference list. It looks doxygen (or bibtex) don't support longer key.
For example, my bib file looks like
#incollection{mcmaster_phenology_,
title = {The {DSSAT} cropping system model},
volume = {18},
journaltitle = {European Journal of Agronomy},
author = {A, F.},
}
#article{mcmaster_phenology_1,
title = {The {DSSAT} cropping system model},
volume = {18},
journaltitle = {European Journal of Agronomy},
author = {A, F.},
}
My text.cs file looks
namespace Test
{
/// <summary>
/// A test class
/// </summary>
/// <remarks>
/// This is test citation, see \cite mcmaster_phenology_ and
/// \cite mcmaster_phenology_1.
/// </remarks>
public class TestClass
{
}
}
The warning message is:
warning: \cite command to 'mcmaster_phenology_1' does not have an associated number
The final html is
This is test citation, see [1] and [mcmaster_phenology_1].
Seems the maximum length of key is 19 characters. It looks a bug for me. How should I fix it? Thank for any suggestions.
Related
We can easily put Doc comments for Dart Class variables e.g.
class SomeClass {
/// Class variable Doc Comment.
var someVariable;
}
How can I do the same for Dart Function parameters e.g. I tried this
void someFunction(
{/// Function parameter documentation
String funParameter="Some Default Value"}
) {
}
But it's not showing anything. If it's not possible please suggest me any alternative.
It is against the Effective Dart conventions to document parameters of functions using a direct syntax like that. Instead, use prose to describe the parameter and how it relates to the function's purpose.
// Instead of this
/// someFunction
/// #funParameter Does something fun
void someFunction({ String funParameter="Some Default Value" }) ...
// Or this
/// someFunction
void someFunction({
/// Does something fun
String funParameter="Some Default Value"
}) ...
// Do this
/// Does something fun with the [funParameter].
void someFunction({ String funParameter="Some Default Value" }) ...
Here's perhaps a more practical example:
/// Takes the values [a] and [b] and returns their sum. Optionally a
/// third parameter [c] can be provided and it will be added to the
/// sum as well.
int add(int a, int b, [int c = 0]) ...
You should use the doc comment like this:
/// the function uses [funParameter] to do stuff
void someFunction({String funParameter = "Some Default Value"}) {
// ..
}
How can one run doxygen in "verification" mode? (parse all documentation, and emit warnings if so configured, but generate no output files).
I tried with the following doxygen configuration file:
DOXYFILE_ENCODING = UTF-8
QUIET = YES
INHERIT_DOCS = YES
EXTRACT_STATIC = YES
EXTRACT_PRIVATE = NO
WARN_NO_PARAMDOC = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_FORMAT = $file($line): $text
GENERATE_HTML = NO
GENERATE_LATEX = NO
INPUT += MySource.cs
Source file:
/// <summary>
/// My namespace documentation
/// </summary>
namespace MyNamespace
{
/// <summary>
/// My class documentation
/// </summary>
public class MyClass
{
/// <summary>
/// My function documentation
/// </summary>
/// <param name="param">The parameter</param>
/// <returns>My return value</returns>
public bool MyFunction(string param)
{
return true;
}
}
}
This generates the following warning:
warning: No output formats selected! Set at least one of the main GENERATE_* options to YES.
which is a bit of a bummer since I want to set WARN_AS_ERROR = YES. But additionally I get additional errors like:
MyClass.cs(17):warning: parameters of member MyNamespace.MyClass.My
Function are not (all) documented
MyClass.cs(17):warning: return type of member MyNamespace.MyClass.M
yFunction is not documented
If I set GENERATE_HTML = YES however I have no warnings, so the documentation itself is fine. Am I doing something wrong or is this a bug?
Doxygen is not intended for just checking whether or not the documentation is complete. The purpose of doxygen is to generate documentation. Some error first appear when the complete documentation is generated / can be properly checked when the documentation is generated.
Workaround: Set the QUIET = YES and WARN_LOGFILE configuration option to a file, then parse the content of this file. The warning
warning: No output formats selected! Set at least one of the main GENERATE_* options to YES.
is not being printed to that file.
I am using doxygen to create a HTML documentation for a C++ library.
Right now I have the problem that code listings created with \code ... \endcode produce listings where each line starts with an asterisk.
Example:
Have a look at the following code sample:
\code
int a = 5;
int b = func(a);
\endcode
Output:
Have a look at the following code sample:
* int a = 5;
* int b = func(a);
I cannot explain this behaviour -- especially because I use /// instead of /** to mark lines as doxygen documentation. The issue happens for both formattings though.
Does anyone know how to resolve this?
(I am using doxygen 1.8.5)
This is indeed an unfortunate regression in 1.8.5.
I've just pushed a fix to GitHub. Please let me know if it fixes the problem.
It seems this is a bug. Bugzilla entry.
Also this bug could be related.
I managed to get a workaround by changing the following snippet
/// Have a look at the following code sample:
/// \code
/// int a = 5;
/// int b = func(a);
/// \endcode
to the following (note that there are only two slashes):
/// Have a look at the following code sample:
// \code
// int a = 5;
// int b = func(a);
/// \endcode
I am not happy with this because it requires to re-layout all comments and the formatting feels very much unnatural.
In Python I have a flag class that I have found very useful. I'm newbe to c++, and can not seem to replicate this python functionality in c++. Rather than put up c++ code that didn't work, here's what I am looking to replicate, and I need some suggestions on where to go, templates, virtual, or ??
The requirement is being able to dynamically alter the members of the class, in python it's modifying the dict element of the class it's self that enables this.
In python:
import sys
args = []
... loads up args[] with keys:values looping through sys.argv[] ... blah blah blah
class Flag:
def __ init __(self, **args):
self. __ dict __.update(args)
now we enable flag.dynamicproperty
flag = Flag(**dict(args))
An example of use:
$ python script.py somedesc1 someval1 somedesc2 someval2
What this does is enables me to pass in parameters, as above, from the command-line and assign any number of them on-the-fly, and make then accessible by a flag.property (eg flag.somedesc1) call which returns somval1. Another way to maybe think about this is dynamically adding a key:value property to a C++ class.
An example of use in python code :
if flag.somedesc1 != '10': print someval1
I can't seem to make a comparable c++ work. I've looked into polymorphism, but these have to be assigned dynamically and then be accessible as a property of the class.
Ideas??? Surely c++ can do this, I'm just not sure where to start.
Okay, here is the solution I worked out; haven't tested it yet, but should work close enough to fit my needs using this format
flag.find(filename)
enum { filename, workers, runtime };
class flag {
vector<string> helplist;
public:
int add(int argc, char *argv[], string flag, string value, string description) {
string flagvalue;
flagvalue = value;
helplist.push_back(description);
for (int i; i < argv.length(); i++) {
if (argv[i]==flag) {
flagvalue = argv[i+1];
}
}
}
void showhelp() {
for (int i; i < helplist.length(); i++) {
cout << helplist[i] << endl;
}
}
};
No, you can't do this in C++. In C++, the members of a class are defined 100% at compile time. You cannot add any at runtime. The way to do this in C++ would be to have a member variable that's a map<string,string> that holds the key/value pairs, and then have a function string getVariable(string) that returns the value in the dictionary for that key.
I have a .NET Web Service(.asmx, not .svc) that accepts a string via HTTP POST. The strings it accepts are xml infosets I then parse via XElement.Parse. Once parsed into an XElement instance, I add a node to one of the elements within the instance.
The problem I'm having is that if a string representing an xml infoset comes through with then for some reason, me adding a node to the element XElement throws an exception such as "' ', hexadecimal value 0x06, is an invalid character. Line 1, position 40.". I get a wide array of 0x(*) errors thrown. If I don't attempt to add nodes to the XElement, everythings fine. Here's how I'm adding the element:
var prospect = doc.Element("prospect");
var provider = prospect.Element("provider");
provider.Add(new XElement("id",
new XAttribute("reservation-code",
reservationCode)
));
Is there some sort of string conversion I ought to be doing somewhere?
XML does not allow some Unicode characters. See the XML 1.0 Specification. Unfortunately, there is no standard way to escape those characters in XML, too. For example, you cannot escape it in valid XML using because of the Well-formedness constraint: Legal Character (see character references).
The XElement.ToString() has the check for those characters turned on. However, .NET does provide a way to turn character checking off. It is off by default in the System.Xml.XmlWriter instances. Therefore the following code will work:
/// <summary>
/// Returns the XML string of the <paramref name="xElement"/> WITHOUT CHARACTER CHECKING.
/// </summary>
/// <param name="xElement"></param>
/// <returns></returns>
public static string ToStringWithoutCharacterChecking(this XElement xElement)
{
using (System.IO.StringWriter stringWriter = new System.IO.StringWriter())
{
using (System.Xml.XmlTextWriter xmlTextWriter = new XmlTextWriter(stringWriter))
{
xElement.WriteTo(xmlTextWriter);
}
return stringWriter.ToString();
}
}
Notice however that if you create an System.Xml.XmlWriter instance using System.Xml.XmlWriterSettings, the default is true for character checking. Therefore if you use System.Xml.XmlWriterSettings and want to turn off character checking, use:
XmlWriterSettings s = new XmlWriterSettings();
s.CheckCharacters = false;
using(XmlWriter w = XmlWriter.Create(..., s))
{
//etc.
}
thanks a lot, which solved my problem when I using linq to xsd.
here is my code:
//not using container.Save(new StreamWriter(toStream, new UTF8Encoding(false)));
instead using codes:
using (XmlWriter w = XmlWriter.Create(new StreamWriter(toStream, new UTF8Encoding(false)), new XmlWriterSettings
{//http://stackoverflow.com/questions/5709831/xelement-utf-8-issue
//http://stackoverflow.com/questions/10057171/xdocument-prevent-invalid-charachters
Indent = true,
CheckCharacters = false
}))
{
XTypedServices.Save(w, container.Untyped);
}
toStream.Flush();