Hello there
How I can add a code-snippet inside a documentation comment for a function
/*
** This is my special function
** it is used like this
** ```ft_printf("I am %d years too early for marriage", -1)``` <<-- like this?
*
int ft_printf(const char *fmt, ...);
I am trying to become more communicative in the work i leave behind.
I did my best to find answers on the internet, just couldn't express my self well enough to get the answers i needed. hopefully a fellow human well help
There are lots of ways to do it, so this is very subjective. One common way is to have a function banner for each function that describes the purpose of the function, its parameters, and the return value, e.g.
///////////////////////////////////////////////////////////////////////////////
///
/// #par Function Name
/// printf_str
///
/// #brief Log a str to the debug stream.
///
/// #param const char * String to be output
///
/// #retval int 0 for success, otherwise an error code
///
////////////////////////////////////////////////////////////////////////////////
int printf_str( const char * str )
You can then use tools like doxygen to generate documentation from your code.
Related
I’ve been recently getting into OS development (completely from scratch), and I’m stuck on an issue where plotting pixels to the screen does not seem to work at all.
For reference, I’m using EDK2 for the UEFI utilities and compiling my bootloader using its build system.
I obtain the framebuffer from the GOP handle after setting my wanted mode (which should be 1366x768, BGRA colour format), but writing any value to the framebuffer memory space seems to not translate anything to the screen. Here are the projects (bootloader and OS) for references:
* OS: https://github.com/kernel-dev/kernelOS
* Bootloader: https://github.com/kernel-dev/kernelOSBootloader
Furthermore, here are the relevant snippets of code that should work, but don’t:
* Function declarations: https://github.com/kernel-dev/kernelOS/blob/main/src/Kernel/Graphics/KernGraphics.c
* Calling the function for clearing the screen: https://github.com/kernel-dev/kernelOS/blob/main/src/Kernel/Kernel.c
Solved
The reason why it wasn't working is because I wasn't properly getting the passed down arguments in my kernel.
This is how it looked like:
// Entry point for kernel
VOID
KernMain (
IN EFI_RUNTIME_SERVICES *RT,
IN EFI_KERN_MEMORY_MAP *MemoryMap,
IN ACPI_DIFFERENTIATED_SYSTEM_DESCRIPTOR_TABLE *Dsdt,
IN KERN_FRAMEBUFFER *Framebuffer)
{
ScreenClearTerminal (Framebuffer);
//
// Should never reach here.
// Will be removed later.
//
while (TRUE) {};
}
However, the way I actually pass them down is like this:
//
// Prepare the arguments to be passed down.
//
LoaderBlock->MemoryMap = &MemoryMap;
LoaderBlock->Dsdt = Dsdt;
LoaderBlock->RT = SystemTable->RuntimeServices;
LoaderBlock->Framebuffer = FB;
//
// Exit boot services.
//
/* ... */
//
// Locate the EP function and call it with the arguments.
//
typedef void (__attribute__((ms_abi)) *EntryPointFunction) (LOADER_PARAMS *LP);
EntryPointFunction EntryPointPlaceholder = (EntryPointFunction) (BaseAddress + EntryPoint);
EntryPointPlaceholder (LoaderBlock);
It's contained inside of a struct. So the appropriate way to obtain them would be like this:
/**
A structure used to "contain" all
the parameters to be passed down
to the kernel's EP.
**/
typedef struct {
EFI_RUNTIME_SERVICES *RT; /// Pointer to the runtime services.
EFI_KERN_MEMORY_MAP *MemoryMap; /// Pointer to the EFI_KERN_MEMORY_MAP.
ACPI_DIFFERENTIATED_SYSTEM_DESCRIPTOR_TABLE **Dsdt; /// Pointer to the DSDT pointer.
KERN_FRAMEBUFFER *Framebuffer; /// Pointer to the KERN_FRAMEBUFFER.
} LOADER_PARAMS;
// Entry point for kernel
VOID
KernMain (
LOADER_PARAMS *LP)
{
ScreenClearTerminal (LP->Framebuffer);
//
// Should never reach here.
// Will be removed later.
//
while (TRUE) {};
}
or, alternatively keeping the old method, but alternating the way they're passed down:
//
// Locate the EP function and call it with the arguments.
//
typedef void (__attribute__((ms_abi)) *EntryPointFunction) (
EFI_RUNTIME_SERVICES *RT,
EFI_KERN_MEMORY_MAP *MemoryMap,
ACPI_DIFFERENTIATED_SYSTEM_DESCRIPTOR_TABLE **Dsdt,
KERN_FRAMEBUFFER *Framebuffer
);
EntryPointFunction EntryPointPlaceholder = (EntryPointFunction) (BaseAddress + EntryPoint);
EntryPointPlaceholder (
SystemTable->RuntimeServices,
&MemoryMap,
Dsdt,
FB);
Completely my bad lol.
Thank you to #user123 and #Dave S for helping me.
When porting from NAOqi to qi framework I achieved a partial success. I do however still have the following problem.
I do not know how to implement sound processing with ALSoundExtractor in qi framework.
In old Naoqi, there is an example:
http://doc.aldebaran.com/2-8/dev/cpp/examples/audio/soundprocessing/soundprocessing.html
where a class is created:
class ALSoundProcessing : public ALSoundExtractor
then a function overriding a virtual function is declared, one that is used for sound processing:
void process(...)
What I don't now is:
How to create a class in qi framework that inherits from the old style class ALSoundExtractor?
How to declare a function that is overriding the virtual function - technically the base class function process() expects variables in old AL:: convention.
Alternatively, is there any other way to read the audio channels?
I never worked with ALExtractor nor ALSoundExtractor, but here is what I know.
How to create a class in qi framework that inherits from the old style class ALSoundExtractor?
in the old Naoqi, an "ALExtractor"
could run either from within the main process (using autoload.ini) or from another one (known as remote mode). With the qi framework, only the remote mode is supported.
could inherit from ALExtractor or ALAudioExtractor to get some code factored out. Those classes have not been ported to the qi framework. So if you don't want to keep using libnaoqi, you should find a way to do without them.
Good news: inheriting from them never was really needed. You'll find yourself in a similar position as in the following question where an extractor is implemented in python (and thus cannot inherit from a C++ class, nor be loaded in the main process from autoload.ini).
NAO robot remote audio problems
How to declare a function that is overriding the virtual function - technically the base class function process() expects variables in old AL:: convention.
Whenever you use the "old Naoqi" you're actually using a compatibility layer on top of the qi framework.
So whenever you use the "old Naoqi", you're already using the qi framework.
libqi's qi::AnyValue is extensible at runtime, libnaoqi extends it to let it know how to handle an ALValue: how to convert it into primitive types (floating point number, list of ints, string, buffer, etc.).
So whenever an old ALSoundExtractor receives an AL::ALvalue, it is actually a qi::AnyValue which has been converted into an ALValue just before calling the process() method.
If you don't link with libnaoqi, you won't be able to use the value as an ALValue, but you can use it as a qi::AnyValue or even use it as a primitive type.
The original prototype is (cfr doxygen http://doc.aldebaran.com/2-8/ref/libalaudio/classAL_1_1ALSoundExtractor.html) is
void ALSoundExtractor::process (const int &nbOfChannels, const int &nbrOfSamplesByChannel, const AL_SOUND_FORMAT *buffer, const ALValue ×tamp);
Since timestamp is probably a list of two ints, I would try something like this
void TmpSoundExtractor::process (const int &nbOfChannels, const int &nbrOfSamplesByChannel, qi::AnyValue buffer, const std::vector<int> ×tamp);
I'm not sure how to handle the buffer variable, but let first get the rest working.
To use this API, you must write a Qi Service that advertises this method:
void processRemote(
int nbOfChannels,
int nbrOfSamplesByChannel,
const qi::AnyValue& timestamp,
const qi::AnyValue& buffer)
{
std::pair<char*, size_t> charBuffer = value.unwrap().asRaw();
const signed short* data = (const signed short*)charBuffer.first;
// process the data like in the example.
}
Note that with the Qi framework:
AL::ALValue is replaced by qi::AnyValue.
Getting the binary data (aka "raw") is slightly different.
AL_SOUND_FORMAT is replaced by signed short*.
ALSoundExtractor is not available, so we needed to do the conversion to const AL_SOUND_FORMAT* by ourselves.
Say your service is registered as "MySoundExtractor", you will have to tell ALAudioDevice to start the sound extraction and send the data to your service as follows:
auto audio = session->service("ALAudioDevice").value();
int nNbrChannelFlag = 0; // ALL_Channels: 0, AL::LEFTCHANNEL: 1, AL::RIGHTCHANNEL: 2; AL::FRONTCHANNEL: 3 or AL::REARCHANNEL: 4.
int nDeinterleave = 0;
int nSampleRate = 48000;
audio->setClientPreferences("MySoundExtractor", nSampleRate, nNbrChannelFlag, nDeinterleave);
audio->subscribe("MySoundExtractor");
Note that I did not test this code, so let me know what may be wrong.
The following is what has eventually worked for me and concludes the topic.
// **************** service.h ****************
typedef signed short AL_SOUND_FORMAT; // copy from alaudio/alsoundextractor.h
class SoundProcessing
{
public:
SoundProcessing(qi::SessionPtr session);
void init(void); // a replacement for a function automatically called in NAOqi 2.1.4
virtual ~SoundProcessing(void);
void processRemote(const int& nbOfChannels, const int& nbrOfSamplesByChannel, const qi::AnyValue& timestamp, const qi::AnyValue& buffer);
private:
qi::SessionPtr _session;
qi::AnyObject audio;
};
// **************** service.cpp ****************
SoundProcessing::SoundProcessing(qi::SessionPtr session) : _session(session)
{
_session->waitForService("ALAudioDevice");
audio = _session->service("ALAudioDevice");
} // constructor
QI_REGISTER_MT_OBJECT(SoundProcessing, init, processRemote);
SoundProcessing::~SoundProcessing(void)
{
audio.call<qi::AnyValue>("unsubscribe", "SoundProcessing");
} // destructor
void SoundProcessing::init(void)
{
audio.call<qi::AnyValue>("setClientPreferences",
"SoundProcessing",
_FREQ48K, // 48000 Hz requested
0,
1
);
audio.call<qi::AnyValue>("subscribe", "SoundProcessing");
} // SoundProcessing::init
void SoundProcessing::processRemote(const int& nbOfChannels,const int& nbrOfSamplesByChannel, const qi::AnyValue& timestamp, const qi::AnyValue& qibuffer)
{
std::pair<char*, size_t> charBuffer = qibuffer.unwrap().asRaw();
AL_SOUND_FORMAT *buffer = (AL_SOUND_FORMAT *)charBuffer.first;
(...)
} // SoundProcessing::process
// **************** main.cpp ****************
int main(int argc, char* argv[])
{
qi::ApplicationSession app(argc, argv);
app.start();
qi::SessionPtr session = app.session();
session->registerService("SoundProcessing", qi::AnyObject(boost::make_shared<SoundProcessing>(session)));
qi::AnyObject sp = session->service("SoundProcessing");
sp.call<qi::AnyValue>("init");
app.run();
return 0;
}
The following is what I did. The code compiles, but I won't have a chance to test it on a live robot for about one week or so.
typedef signed short AL_SOUND_FORMAT; // copy from alaudio/alsoundextractor.h
void process(const int& nbOfChannels, const int& nbrOfSamplesByChannel, const AL_SOUND_FORMAT *buffer, const qi::AnyValue& timeStamp); // I do not use the timeStamp variable in my code, so AnyValue would work?
qi::AnyObject audioDevice = _session->service("ALAudioDevice"); // same variable name as in the original ALSoundExtractor module, just as a convenience
audioDevice.call<qi::AnyValue>("setClientPreferences", audioDevice.call<qi::AnyValue>("getName"), 48000, 0, 1);
audioDevice.call<qi::AnyValue>("subscribe", audioDevice.call<qi::AnyValue>("getName")); // this is the key call
audioDevice.call<qi::AnyValue>("startDetection"); // is it still necessary?
My question is - do I do it right now? If I cannot override the virtual function process(), does subscribing of my module guarantee a callback to my process(...)?
I was trying to solve this old lab sheet-
http://csis.bits-pilani.ac.in/faculty/murali/dsa-10/labsheet3_sec4.pdf
So my question is I have to use this method -
int createMaze(Maze *pm, char *mazefilename)
This will enter values in the Maze.But since it is not returning the Maze how can I use it in this method-
Boolean findCheese(Maze m, int n, int posi, int posj, char
**path_so_far, int past_i, int past_j)
Also I cant call findCheese method from createMaze I have to call both of them from another driver.c file.SO is the definitions of the methods wrong or is there someway I can use Maze in both the methods?
In the document you linked to, it says:
Create a driver file maze.c for meeting the objectives of this problem.
This creates the Maze using createMaze. It then calls findCheese to determine the path.
The code will look something like:
Maze m;
createMaze(&m, "some file name");
findCheese(m, ... rest of the arguments ...);
I have a library which provides function calls to a user as below:
int* g_ID = NULL;
void processing(int p1, char p2)
{
int ID = newID();
g_ID = &ID;
callback(p1, p2);
return ID;
}
void SendResponse()
{
sendID(*g_ID);
}
The user sets up its application by registering its callback function with the signature void (f*)(int p1, char p2) and should not have knowledge about the ID used internally the library. So the user space code looks something like:
main()
{
RegisterCallback(HandleRequest);
while (inProgress())
sleep(1); /* just sleep here */
}
void (HandleRequest*)(int val1, char val2)
{
/* ... do something user specific ... */
SendResponse();
return;
}
The problem here is, that the library (handling IDs and g_ID is not thread safe) !! User's callback is invoked asynchronously by other library functions, as threads. Several threads can be executed this way in parallel. But I won't give the user visibility of library internal IDs.
I know the code snippets above are not perfect. There're just to demonstrate my intention ... SendResponse() is not yet implemented ;-).
I hope, someone can give some ideas how to "implement" SendResponse() and to keep thread safety.
You could use a threadlocal here to keep the g_ID, rather than making using a global. This will work in the scenario, as I understand it, that there may be multiple concurrent calls to process() from different threads, but that the process() method is as shown - that the SendResponse() call will only occur within the scope (runtime scope, not lexical) of the callback() method. That is true in the code shown. It could be untrue if HandleRequest did something exotic like kick off another thread an then return (but you could certainly ban that by documentation).
The other, more classic, approach is to encapsulate all the state you care about, like g_ID, into a void *, or opaque_state * or whatever, that you pass to the callback, and then methods like SendRespose() take that as an argument. If you don't like void * you can implement the opaque_state * version without exposing any details of that structure using a forward declaration.
We have a function header format that we have to follow. It basically looks like this
/**
* Name: blah
*
* Parameters:
* int foo
* bool bar
*
* .....
We are attempting to generate some documents with doxygen, but one issue is that when we change he code to:
/**
* Name: blah
*
* Parameters:
* \param int foo
* \param bool bar
*
* .....
When Doxygen generates the html comments, it adds the Parameters title. We are required to have line 4, so this creates documents with 2 lines that say Parameters, the first is from line 4 and the second Doxygen auto inserts.
What I'm hoping I can do is either have Doxygen ignore line 4 or add have it not insert it's own "Parameters:" title. Anyone know if this is possible?
The simple solution is to remove the "Parameters:" text altogether; it is entirely redundant since the Doxygen mark-up makes it perfectly clear that they are parameters!
For that matter the "Name:" label is entirely redundant too, and forces you to place the name in both the comment and the code. Why would you need that? It's name is right there in the code. It is an unnecessary comment maintenance headache, and Doxygen will use teh name in the code not the name in the comment in the generated documentation.
If you must attempt to mix your existing format with a Doxygen compatible format it would be easier to use C++/C99 line comments rather than block comments; most C compilers support them:
// Name: blah
//
// Parameters:
/// \param foo Description of foo
/// \param bar Description of bar
Note \param <type> <name> is not correct Doxygen syntax; it is \param <name> <description>. Doxygen gets the type from the code; again specifying the type in the comment is entirely redundant, and another maintenance headache.
I would strongly suggest that you employ a more Doxygen and maintenance friendly function boiler-plate altogether. I use the following basic form (for what its worth):
//! #brief Brief description
//!
//! Full description if necessary.
//! #param p1 p1 description
//! #param p2 p2 description
//! #return Return value description
int foobar( int p1, int p2 ) ;
Obviously whether you use /// or //! and \ or # is a matter of preference.