Doxygen documenting template parameters
Pubby must be kidding. Good docs is when you never look at the code. You read explanation comments in a header, and you don't even care to see at the implementation, that is, you don't care about a code style, formatting, readability and whatever more — this is a good docs. Doxygen is just a tool for extracting these docs from a source code ideally from headers. Add a comment. Active Oldest Votes. Document it! Improve this answer.
Mark Gates 2 2 silver badges 6 6 bronze badges. David Hammen David Hammen Yes, it's a typedef, but that typedef contains the type that is the result of evaluating the compile-time "function" specified. I would dispute that there is no return here. Formally classes don't have return values, but logically the type typedef is a return.
And would be better documented in the main documentation body for the class than as a separate member. One could argue that there is a return here, in the same sense this this struct definition is a function.
This actually should be selected as the right answer — Sergei Krivonos. Most-recent link to tparam on Doxygen documentation: doxygen. Show 1 more comment. Antoine Antoine I agree, the majority of boost documentation is very good and it certainly makes sense to follow their approach. Very good information here. I had to use just -Wdocumentation to get it working. Doesn't strictly answer OP's question, though.
Look at the source code. The little commentary that exists is at best poor. It's not fair to use GNU's lousy commentary as an example of the failures of doxygen.
Separate the files or directories with spaces. Generates the index. By default all members of a group must be documented explicitly. The default value is: NO. Documented entities will be cross-referenced with these sources. I have created it for you. Searching for include files Searching for example files Searching for images Searching for dot files Searching for msc files Searching for dia files Building group list Generating file member index Generating example index Figure 1: Documentation of type alis MathFunc.
Be sure to check the Scan recursively button to make Doxygen search all the subfolders too. If you run Doxygen with the settings above, giving it an empty folder as a source directory, you would get something like this.
As you can see in the above picture, The logo which I created for this tutorial , the project name, version, and synopsis are shown at the top of the generated HTML. Keep the Height of the Logo to px, to ensure a good fit as Doxygen is not smart enough to resize it for us.
But some people prefer to document all entities, as this would point out the functions which are not documented, as an indicator that it needs documentation. I leave it up to you to experiment with both options and decide on one. This tab lets you select the type of output you need.
I personally never use Latex so I unchecked that and other than that I have kept the default settings here as shown in the picture below. I have not experimented much with the diagram generation options of Doxygen as most of these are geared towards the object-oriented languages. I personally prefer just the architecture diagrams, which I make myself for my projects so hence I keep the diagrams option to No diagrams as shown below.
Instead, we can get the output to start from the root directory of the project itself. As we saw above, there are 2 levels of description for any given entity, a brief description, and detailed description. The first 4 options mentioned above are pretty self-explanatory.
It basically prints a line at the end of pages showing structs the list of files used to generate the documentation. For example, consider the following header file. Basically we are trying to eliminate this portion of the documentation by unchecking that option.
For a simple sample code, it might look okay to have this part, but for a real-word project, the clutter can add up and intrude and actual useful documentation. I suggest you experiment for yourself and find out if you need this portion or not. This basically controls the log printed as you run the Doxygen and has nothing to do with the content of the generated HTML. This one contains the options to control the files which are being used to generate the documentation.
While writing C code, we often find ourselves using libraries from 3rd parties. These libraries usually contain a large number of files and it might add unnecessary clutter to the documentation.
If you have folders that you need to exclude from the documentation, then you can add them to the exclude tab as shown below.
I normally remember the modules a particular struct is placed in and not its actual name so I uncheck this option to eliminate documentation like this. You can experiment and figure out for yourself if you need it. Again you can experiment for yourself to see and decide if preprocessing makes better sense to you. The diagrams generated by Doxygen are more focussed on object-oriented software and hence you can uncheck the class diagrams. But I like to keep my diagrams at an architecture level and not at a code level and hence I prefer not to use it.
You can download the doxyfile that is generated by following this tutorial through this link and use it on your own projects!
0コメント