In a C++ project, I describe methods and functions in my headers like so:
int foo(float, bool, std::string);
and in my implementation, name the parameters:
int
foo(float f,
bool b,
std::string str)
{
...
}
and if I generate my documentation with Doxygen with SOURCE_BROWSER=NO, VERBATIM_HEADERS=NO and EXTRACT_ALL=YES then the resulting documentation contains the function signature with the parameter names which is what I want. But I also end up with all of my .cpp files in the 'File List' section alongside the headers.
I want to completely hide my source files but then I want to also have my documentation to contain parameter names without having to go through the project and add thousands of them to the includes myself.
I have tried adding the src/ folder to EXCLUDE which does hide the sources but then they aren't parsed at all and the opposite problem arises where the parameters are nameless again.
Is there any way I can eat my cake and have it too?
It turns out if I disable EXTRACT_ALL=yes and add #file to the start of only the files I want to show (so all the headers) then I can retain the parameter names from sources while hiding the files.
Perhaps not the best solution given undocumented functions will no longer display but since they all are in this project it does not pose a problem.
Related
I'm using sphinx to document a C++ project, in which there are various pages that document a class. In these I've used :noindex: for the class methods, since otherwise they clutter the whole project Index page.
.. cpp:function:: void foo(int a)
:noindex:
However, one of the differences this also makes is that I cannot create local in-page links. Eg., in the doc body for a different method:
The first argument is the same as that to :cpp:func:`foo`.
Without :noindex: on foo(), this link works. With it, no error is generated and there is a link, but it's dead/useless/goes nowhere.
How can I get around this?
Manual creation of local links is fairly simple in reStructuredText:
.. _`foo()`
.. cpp:function:: void foo(int a)
:noindex:
Defines the target without changing the appearance of anything. To link it,
The first argument is the same as that to `foo()`_.
Notice the location of the underscore is front to back. The ticks are needed if you want to include the parentheses; if the label is plain alphanumeric they can be discarded.
A few shortcomings:
You can't wrap this in mark-up, eg., to monospace or emphasize the link text.
There doesn't seem to be a way to substitute the link text.
I have a configuration file system written in C++ which uses the yaml-cpp library to parse and write to YAML files. I have this as part of my static library.
I would like the ability to return a default value for a field that is requested by a user of the library (calling from their code), but which has not been defined in the user's YAML file.
For example say the user wants to use the field foo from their custom config.yaml file:
int bar = config_reader.read<int>( "config.yaml", "foo" );
If they have foo: 10 in their config.yaml then bar will be set to 10. However I would also like to provide a default value (for example 4) in the case where foo is omitted from config.yaml.
There are two possibilities I have thought of:
Have a set of static maps between field names and default values in a cpp file which gets compiled into the static library, however I will need to have different maps for different types and I feel this could get messy with type checking and maybe requiring template specialization methods.
Have a YAML file which contains all of the default values for expected fields, which the configuration system falls back on if it cannot find the field in the user's config file. I think this would be the preferred solution for me, but I cannot think of a neat way of packaging this YAML file. I would rather the user didn't have to copy or point to this file each time they set up a new project linking the static library.
I would provide the defaults in a YAML file in a global (i.e. non-user specific place) and allow to override the values with user-specific ones.
Consider just throwing an error if the global defaults are missing an entry, this will not happen by accident.
The global defaults you can put in /etc/default/YOUBLIBNAME.yaml. The user's configuration nowadays mostly follows the XDG base directory specification. For that use $XDG_CONFIG_HOME/YOURLIBNAME/config.yaml if XDG_CONFIG_HOME is set in the environment, if not set use $HOME/.config/YOURLIBNAME/config.yaml.
If your library has to work under Windows, I would put the user specific data under %APPDATA% in a subdir YOURBLINAME.
I have a large C++ software application documented with doxygen. How can I set it up so that I can generate subdocuments for specific classes? The classes are documented with in-source commenting, their own .dox files, and images/ directory. I need to be able to generate a standalone pdf file specific to a single class.
I can use grouping to identify what will be included in that subdocument, but how do I generate output for a single group?
If you have a specific .dox file per requested output entity, then all you need to do is define in that file as input the files declaring and defining that class.
Say for example you want an output only for class MyClass which is declared in file myclass.hpp and whose implementation is in myclass.cpp, then in myclass.dox, just add this:
INPUT = ./myclass.cpp \
./myclass.hpp
Of course, you can have different paths for .cpp and .hpp. Or you can document more than one class.
Then, run doxygen on that myclass.dox file.
Also watch out for the output folder name. For the html output, the default name is html so you might want to rename it to avoid mixing up all the different outputs. For example, you might want to add in the dox file something like:
HTML_OUTPUT = html_myclass
I have a multi file template in resharper and I can use $NAME$ macro to get the name of the original file to use to name the other files in the template. But I also want to use the $NAME$ of the original file in the content of the other file template.
Is this possible? I can't see a macro which seems suitable for the internal variables as onlt the Current File Name seems available.
Anyone know if this is possible or how I might workaround this?
As a workaround, you may create a parameter $FILENAME$ (macro "Current file name without extension") in the first file e.g. in the comments, like:
class Foo
{
//$FILENAME$
}
Then you may call this parameter in other files of the multifile template - this parameter will contain the name of the first file since the first file will be generated before other ones.
Unfortunately, there isn't a macro that will give you this. I've added a feature request that you can vote on and track (and more specific detail as to what your requirements are would be useful) - http://youtrack.jetbrains.com/issue/RSRP-415055
It is possible to write your own macros as part of a plugin, but there isn't a sure-fire way of getting the name of the first document in the created file set. The IHotspotSessionContext instance that is passed to the macro via IHotspotSession.Context property includes an enumerable of IDocument, from which you can get IDocument.Moniker, which will be the full path for file based documents. However, there's no guarantee of the order of the enumerable - it's backed by a hashset. You might be able to rely on implementation details (small set, no removes) to be able to use the first document as the original, but there is really no guarantee of this.
So I'm tired of creating two new files for every class I make. AFAIK, macros don't record actions such as creating new files. Snippets also can't create new files. I want to press a kinda hotkey to create a new .h and .cpp file with a specified name. Maybe with a class template.
You can use https://sublime.wbond.net/packages/AdvancedNewFile to create multiple files at the same time with the curly brace expansion. For example, inputting test.{cpp,h} will create test.cpp and test.h. You will need to set posix_input to true for the expansion to work. Templates with expansion do not work (right now anyways), but that may change in the future. There may be other plugins with much more specific functionality out there, but I do not know of them.