This is either a bug in Doxygen or I am missing something. It is very easy to reproduce as follows:
I have the following class in a foo.h file:
class Foo {
public:
/**
* This is a comment with \code value.
*/
int bar(int value);
};
If I use Doxygen (version 1.8.17) with the default configuration (generated by the doxygen -g command) then class Foo doesn't appear in the produced documentation. If I simply remove the \code symbol in the comment of bar then the class appears. If I put it back, it disappears again and so on.
This looks like a bug. Am I missing something ?
P.S.: I use MacOS 10.15.4 if it makes any difference.
The usage of the command \code is incorrect the closing \endcode is missing.
There are also warnings:
.../aa.h:10: warning: Reached end of file while still inside a (nested) comment. Nesting level 1 (probable line reference: 4)
...
.../aa.h:10: warning: File ended in the middle of a comment block! Perhaps a missing \endcode?
When correcting this you will get the message:
...aa.h:1: warning: Compound Foo is not documented.
but this is clear as the class itself is not documented.
Note it is a bit strange to have \code in a brief description, maybe you should also look at commands like \a, \arg and \param.
Related
so I have an issue where I have this warning in my Error List:
Severity Code Description Project File Line Suppression State
Warning CS7022 The entry point of the program is global code; ignoring 'Program.Main(string[])' entry point. Project DirectoryToProject 23 Active
This is essentially where its throwing
namespace MyProgram
{
class Program
{
static async Task Main(string[] args) => await new Program.MainAsync();
}
static async Task MainAsync()
{.. do stuff.. }
}
That is the line of code that is causing the error. I've tried playing around with the Main class, I did have it with the return type void and had my GetAwaiter and GetResult method called on the MainAsync method.
I've tried researching the error but I've had no luck, so hopefully, this thread will help a few others...
I am currently running on C# 9.0
Visual Studio 2019 Build Version: 16.8.30717.126
EDIT: Forgot to show that the MainAsync was in the file... (Sorry) Im trying to limit the amount of methods I show as 95% of them aren't useful the to question... But the issue is that although my application compiles, when executing my program it quits instantly as if it doesn't know where to start...
EDIT 2:
Thanks to Hans Passant -
If anyone experiences something like this try what he mentioned:
"This is a rather awful C# v9 feature. Project > Properties > Build tab, Advanced button > Language version = 7.3 You should now get a decent error message from the code you didn't know you had to post".
Essentially upon changing back to C# 8.0 I saw it was a different file hidden away causing the issue.
Starting with net5.0, I've found that this error can be caused by having stray semicolons above the namespace keyword. Whether this is a bug or intended behavior is beyond me, however make sure you don't have any standalone semicolons as such:
using System.Linq;
using System.Reflection;
using System.Text;
using System.Threading.Tasks;
; // This will cause CS7022
namespace Tomoe.Commands.Public
Be sure to check all your files and not just Program.cs
EDIT: Apparently this is intended behavior, see https://github.com/dotnet/roslyn/issues/53472.
TL;DR, semicolons above namespaces are interpreted as top level statements. Because nothing is being called in said statement, the program exits. This is the same as doing
static void Main() {
;
}
in your Program.cs. While I do feel some change should be made, the design decision behind this is quite logical and entirely understandable.
EDIT 2: According to jcouv on Github, this is now becoming an error instead of a warning. Hopefully, this "bug" shall harass us no more!
This can happen if a file (any file) in the project has global code, that's to say statements outside of a class.
As mentioned by others, this is caused by a new C# 9 feature that is called "Top-level statements". This Feature enables you to write statements in the global context and the compiler will create it's own Main() based on that.
In my case I had a semicolon after my using statements in any of my files. As far as I know Visual Studio or the compiler don't give you any option to find this "entry-point" without changing any settings as descripted by others in this thread.
My solution was to just create another "Top-level statement entry point" in my project. Due to the fact that there is only one allowed the compiler complains about that.
I just added a semicolon directly after the using statements in my Program.cs. Because this file is one of the first that are processed by the compiler any other file that contains a "Top-level statement" will cause an error.
I've also seen this compiler error in the following scenario. You've written your code with top-level statements. Later, you decide to absorb that logic into a Main() method. (Maybe you find you now need to return an async Task, or you need to modify it to meet a company coding standard, for example.) Even though the following code block will compile (in VS2022 at least), it generates the error in question with a green squiggly beneath Main:
static void Main()
{
Console.WriteLine("Inside the Main() method");
//Do some other work here
}
Where's the issue? The method declaration is correct, and it will run, but even when this is the only code in the Program.cs file, and even when no other entry point is specified in the project/solution settings, we do not get the expected output:
Even the Microsoft documentation isn't much help in this case, because it pretty much repeats in more detail what the error is saying.
What's missing is the Program class definition. Without it, the compiler is still looking for a top-level statement - which it finds, namely static void. Then the next thing it finds is the Main() method declaration, but it finds this after the (unintended) top-level statement static void. Hence, the error sorta makes sense now.
The fix is to wrap the above code in a Program class:
class Program
{
static void Main()
{
Console.WriteLine("Inside the Main() method");
}
}
And now we get the expected output:
I defined a macro in a module, and it works fine.
Now, I'm trying to document said macro with an example. Apparently, I need to manually specify the crate line to ask for macros:
/// ```
/// # #[macro_use] extern crate foo;
/// // Some code
/// ```
However, I now get an error saying:
error: an `extern crate` loading macros must be at the crate root
Apparently the example code is loaded in the macro's module, and does not seem compatible with macro_use...
I can't believe everyone writes macros directly in the root module... right?
Well adding a main function did the trick. My example code did not need to run anything (just compile) so I didn't even bother adding a main function, but apparently adding it puts the code in a virtual "crate root", and it accepts the macro_use. Yay!
So what I did is just add :
/// # fn main() { }
I'd like to avoid getting this annoying:
Generating docs for compound bla_param...
/home/mathieu/Projects/bla_parser.h:57: warning: Found unknown command `\0'
/home/mathieu/Projects/bla_parser.h:57: warning: Found unknown command `\0'
The only option I can think of is a double escaping, and have:
/** Query parameters */
typedef struct bla_param{
char *cclose; /**< list of params, separated by '\\0' */
But this make my code difficult to read, and add extra work to developers when documenting the API...
Any other solution I did not think of ?
Updating to the latest version of Doxygen may address this issue. I was able to reproduce this warning with Doxygen 1.6.2, but it didn't occur in later versions (I tested 1.7.6.1, 1.8.0 and 1.8.2).
I am trying to use Doxygen Automatic link generation to document some enum types. However, it is not generating links for the global enum types. It does generates links for the global struct types. Is there something I am missing? I am using the example provided on the link above. As required, I have documented the file in which the types are defined.
update1: I am using Doxygen version 1.6.3
update2: global structs are ok
Yeah, I had that same issue; i think doxygen thinks they are private or something stupid like that. Try using the \public. Don't forget to do the /*! on the first line
/*! \public
* Enum description goes here
*/
typedef enum {
/**
* Printer control language ZPL
*/
PRINTER_LANGUAGE_ZPL,
/**
* Printer control language CPCL
*/
PRINTER_LANGUAGE_CPCL
} PrinterLanguage;
I was having the same issue. Some header files generated a link for enums and other header files did not. You must explicitly document the file.
Here is a excerpt from this page int the documentation.
http://www.doxygen.nl/manual/docblocks.html#memberdoc
To document a global C function, typedef, enum or preprocessor
definition you must first document the file that contains it (usually
this will be a header file, because that file contains the information
that is exported to other source files).
Attention
Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must
document the file in which they are defined. In other words, there
must at least be a
/*! \file */
or a
/** #file */
line in this file.
I am building a Qt based project, and many Qt classes are found in the target documentation.
How can I tell Doxygen to disable documentation generation for some classes? For Q.*?
Working under the assumption that what you have is something like this: (The question is a little unclear in this regard)
/**
* Some documentation for class X
*/
class X: public osg::Drawable {
...
}
And your problem is that you want to include documentation for class X, but not for class osg::Drawable, the proper technique is to use EXCLUDE_SYMBOLS. For example, in the case above use
EXCLUDE_SYMBOLS = osg::Drawable
If you want to be slightly more rigorous, you can use
EXCLUDE_SYMBOLS = osg::Drawable \
Drawable
Wild-cards are also allowed, so this will also work
EXCLUDE_SYMBOLS = osg::*
If \internal tag does not work, you can try \cond ... \endcond tags for marking a portion of code to be hidden from Doxygen.
EDIT
If you want to exclude specific files, you can use EXCLUDE_PATTERNS variable in Doxyfile configuration file.
Its not the best way but one can mark some portion of the documentation (class, members, ...) with the private. This prevents the piece of code from being included in the output documentation. (I use this to hide copy/move constructors/operators from appearing in the API documentation.)
/*!
* \brief This is included.
*/
class API
{
public:
/*!
* \brief So is this.
*/
API() noexcept;
/// \private
~API() noexcept; /* But this not, though technically public. */
private:
int m_version; /* This is not either. */
}
One should note though that this is a Doxygen extension for PHP, which according to the documentation they should not be used.
For PHP files there are a number of additional commands, that can be used inside classes to make members public, private, or protected even though the language itself doesn't support this notion.
The other option is to use the solution mouviciel provided, but it requires at least two lines.
Though not the correct answer for the detailed question it might be helpful for readers of the question title (like me). It works for classe too!