I have this problem where I added a macro to set the visibility of certain functions to my code like this:
#define PUBLIC_API __attribute__((visibility("default")))
The problem is that it seems to have broken the formatting when displaying the functions in Sphinx..
Changing the function docs from this:
struct conductor* conductor_create(struct conductor_error* err);
to this:
PUBLIC_API struct conductor* conductor_create(struct conductor_error* err);
Is there any way I can get that nice auto-formatting back? I would like to not see the macro there at all if possible..
Here's what I was using in the Sphinx .rst for that part if that's relevant:
C API
=====
```/lib/c++/X2XConductorC.h```
.. doxygenfile:: X2XConductorC.h
:project: X2XConductor
I set up the documentation more or less as described here:
https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
Related
I´m developing software based on C++ in Xcode and want to have (at least) the same convenience for code documentation as if I was developing for Swift or objc.
Example:
std::string myString("hello");
if (myString.empty()) {
// do something
}
If I want to know exactly what .empty() does, I would like to Option-Click on the function and get the documentation overlay with information from e.g. http://en.cppreference.com/w/cpp/string/basic_string/empty, exactly as it does for objc and Swift.
How is this possible?
Current output just looks like this:
You cannot. According to Apple's Xcode release notes, as of Xcode 8.3
3rd party docset support is now deprecated and will no longer be
supported in a future release of Xcode. (30584489)
There are alternate doc browsers, like Dash which allow you to install your own documentation. But this does not give you what you're hoping for.
I have verified that adding a C++.docset into ~/Library/Developer/Shared/Documentation does not work. (likely a directory left over from an earlier Xcode) In fact, removing this directory entirely does not affect Xcode 9.x from correctly displaying the default documentation.
This is for your custom class. You can add your comment like this - in the header I do this
/**
* Method name: name
* Description: returns name
* Parameters: none
*/
here is a sample I did -
#ifndef test_hpp
#define test_hpp
#include <iostream>
#include <string>
class myclass{
private:
std::string name_;
public:
myclass(std::string);
/**
* Method name: name
* Description: returns name
* Parameters: none
*/
std::string name();
};
#endif /* test_hpp */
I'll upvote Deb's answer but I was also looking at this for a little while.
Markdown in Xcode is somewhat brittle in Xcode 9.
It works for function declarations:
And also for callouts:
Documentation comments seems to work well for function declarations, but doesn't work at all for lines of code within the functions.
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() { }
Looking through the C and C++ domains of Sphinx, it doesn't appear to have native support for documenting enums (and much less anonymous enums). As of now, I use cpp:type:: for the enum type, and then a list of all possible values and their description, but that doesn't seem like an ideal way to deal with it, especially since it makes referencing certain values a pain (either I reference just the type, or add an extra marker in front of the value).
Is there a better way to do this? And how would I go about handling anonymous enums?
A project on Github, spdylay, seems to have an approach. One of the header files at
https://github.com/tatsuhiro-t/spdylay/blob/master/lib/includes/spdylay/spdylay.h
has code like this:
/**
* #enum
* Error codes used in the Spdylay library.
*/
typedef enum {
/**
* Invalid argument passed.
*/
SPDYLAY_ERR_INVALID_ARGUMENT = -501,
/**
* Zlib error.
*/
SPDYLAY_ERR_ZLIB = -502,
} spdylay_error;
There some description of how they're doing it at https://github.com/tatsuhiro-t/spdylay/tree/master/doc, which includes using a API generator called mkapiref.py, available at
https://github.com/tatsuhiro-t/spdylay/blob/master/doc/mkapiref.py
The RST it generates for this example is
.. type:: spdylay_error
Error codes used in the Spdylay library.
.. macro:: SPDYLAY_ERR_INVALID_ARGUMENT
(``-501``)
Invalid argument passed.
.. macro:: SPDYLAY_ERR_ZLIB
(``-502``)
Zlib error.
You could take a look and see if it's useful for you.
Sphinx now has support for enums
Here is an example with enum values:
.. enum-class:: partition_affinity_domain
.. enumerator:: \
not_applicable
numa
L4_cache
L3_cache
L2_cache
L1_cache
next_partitionab
Hi Maybe you should consider using doxygen for documentation as it has a lot more native support for c / c++. if you want to retain the sphinx output of your documentation you can output from doxygen as xml, then using Breathe it will take the xml and give you the same sphinx output you are used to having.
Here is an example of documenting an enum in doxygen format from the breathe website.
//! Our toolset
/*! The various tools we can opt to use to crack this particular nut */
enum Tool
{
kHammer = 0, //!< What? It does the job
kNutCrackers, //!< Boring
kNinjaThrowingStars //!< Stealthy
};
hope this helps.
I'm using Eclipse + Qualcomm libraries (in cpp) + Android SDK on Ubuntu. My application runs fine. If I change some code in the qualcomm libraries, it compiles and works correctly.
The problem is: I have changed the name of the project, and I have to change some code in cpp (The name of the function), if I don't do it, I get a Java.lang.UNSATISFIEDLINKERROR.
That's because all the functions have the name as the Android package like this:
Java_org_myproject_marker_MainActivity_onQCARInitializedNative(JNIEnv *, jobject)
Then I define a macro like this:
#define MAIN_ACTIVITY_PREFIX org_myproject_marker_MainActivity
#define VISUALIZER_PREFIX org_myproject_marker_Visualizer
And I change all the correct functions by:
Java_MAIN_ACTIVITY_PREFIX_onQCARInitializedNative(JNIEnv *, jobject)
but I am still getting the Java.lang.UNSATISFIEDLINKERROR exception.
It works if I do it without the #define macro (and write all the lines), but I want to save the cpp code with a top define that changes everything automatically if I need to use it in other projects.
I have read this tutorial. Can't I replace a text inside another text or something like that?
you are looking for string concatenation, like this:
#define MAIN_ACTIVITY_PREFIX(n) Java_org_myproject_marker_MainActivity##n
and then use it like this:
MAIN_ACTIVITY_PREFIX(_onQCARInitializedNative)(JNIEnv *, jobject)
Indeed, a CPP macro wont be expanded in the middle of an identifier. Try with
#define MAIN_ACTIVITY_PREFIX(func) Java_org_myproject_marker_MainActivity##func
That gives you a macro that will prepend Java_org_myproject_marker_MainActivity to the function name you pass it. Use it as:
MAIN_ACTIVITY_PREFIX(_onQCARInitializedNative)(JNIEnv *, jobject) {
...
}
In my software, I use libxml2 and xmlsec to manipulate (obviously) XML data structures. I mainly use XSD schema validation and so far, it works well.
When the data structure input by the client doesn't match the XSD schema, libxml2 (or xmlsec) output some debug strings to the console.
Here is an example:
Entity: line 1: parser error : Start tag expected, '<' not found
DUMMY<?xml
^
While those strings are useful for debugging purposes, I don't want them to appear and polute the console output in the released software. So far, I couldn't find an official way of doing this.
Do you know how to suppress the debug output or (even better) to redirect it to a custom function ?
Many thanks.
I would investigate the xmlSetGenericErrorFunc() and xmlThrDefSetGenericErrorFunc() functions, they seem right. The documentation is .. sparse, though.
Here is some Python code that seems to use these functions to disable error messages, the relevant lines look like this:
# dummy function: no debug output at all
cdef void _nullGenericErrorFunc(void* ctxt, char* msg, ...) nogil:
pass
# setup for global log:
cdef void _initThreadLogging():
# disable generic error lines from libxml2
xmlerror.xmlThrDefSetGenericErrorFunc(NULL, _nullGenericErrorFunc)
xmlerror.xmlSetGenericErrorFunc(NULL, _nullGenericErrorFunc)
I was looking for the same solution for some C code:
static void __xmlGenericErrorFunc (void *ctx, const char *msg, ...) { }
xmlSetGenericErrorFunc(nil, __xmlGenericErrorFunc);
xmlThrDefSetGenericErrorFunc(nil, __xmlGenericErrorFunc);