I'm new to QDoc and I'm trying to figure out if I prefer it over Doxygen. There's one thing that annoys be.
QDoc will only look through *.cpp files for /*!-style comments, so I can't document inline functions and pure virtual functions.
Is there a workaround for this?
You can use the \fn command to refer to a function. For your two cases, put something like this in a .cpp file:
/*!
* \fn void AbstractClass::pureVirtualMethod()
*
* Some info here...
*/
/*!
* \fn void inlineFunction()
*
* Some info here...
*/
Related
What I mean specifically is if it's possible to have some code written, say in C (or some other compiled language), and then expose it and use from within a GJS runtime.
In fact, this is how all of GJS works. Just as node.js is ECMAScript on top of node's own platform, GJS was created so that ECMAScript could be used with the GNOME platform libraries.
This is effectively limited to C libraries written with GObject, but of course anything you can use from C can be wrapped into a GObject-based library. There are Boxed Types for integrating foreign structures into the GLib type system, or you can wrap things into the structure of a GObject subclass.
The principle is pretty straight-forward and relies on use GObject-Introspection Annotiations to express function signatures, memory ownership and so on. Below is a simple example:
/**
* namespace_copy_string:
* #input: (transfer none): an input string
*
* This function copies a string and returns the result.
*
* Returns: (transfer full): a new string
*/
char *
namespace_copy_string (const char *input)
{
return g_strdup (input);
}
The headers and source are then scanned for public symbols with these annotations, and use to generate an XML-format and compiled typelib. meson is the recommended build-system for GObject-based libraries and includes helpers for generating the introspection data. You can also use gi-docgen to easily generate documentation from this output.
Once installed, the result can be imported into any language binding that supports GObject-Introspection (GJS, Python, etc):
const Namespace = imports.gi.Namespace;
let copy = Namespace.copy_string("content");
Every programming course tell us that we shoul use as much comments as possible to make things clear which makes sense. Because you will forget what you did if you read it in the future.
How come professional source codes contain virtually no comments? wouldn't it make it more readable?
Example (istream) from C++:
template<typename _CharT, typename _Traits>
class basic_istream : virtual public basic_ios<_CharT, _Traits>
{
public:
// Types (inherited from basic_ios (27.4.4)):
typedef _CharT char_type;
typedef typename _Traits::int_type int_type;
typedef typename _Traits::pos_type pos_type;
typedef typename _Traits::off_type off_type;
typedef _Traits traits_type;
// Non-standard Types:
typedef basic_streambuf<_CharT, _Traits> __streambuf_type;
typedef basic_ios<_CharT, _Traits> __ios_type;
typedef basic_istream<_CharT, _Traits> __istream_type;
typedef num_get<_CharT, istreambuf_iterator<_CharT, _Traits> >
__num_get_type;
typedef ctype<_CharT> __ctype_type;
protected:
// Data Members:
/**
* The number of characters extracted in the previous unformatted
* function; see gcount().
*/
streamsize _M_gcount;
public:
/**
* #brief Base constructor.
*
* This ctor is almost never called by the user directly, rather from
* derived classes' initialization lists, which pass a pointer to
* their own stream buffer.
*/
explicit
basic_istream(__streambuf_type* __sb)
: _M_gcount(streamsize(0))
{ this->init(__sb); }
The question is about actual policies software companies have concerning comments.
The reason?
Many software developers are already proficient in a certain language, in this case it is C++. While comments do make learning easier for beginners wanting to learn what code means, they become less and less necessary as the programmer moves up in knowledge. For example, the Python code might need some comments to explain it to a beginner:
class House:
def __init__(self, rooms, people):
self.rooms = rooms
self.people = people
myHome = House(3, 5)
print(myHome.rooms)
But advanced programmers might immediately know that it is a script that creates an object.
If you are...
talking about proprietary companies, you're right. Closed-source programs are not meant to be modified, rather, to be distributed as binaries. Companies might do this to obfuscate the code so no one knows what it means. There might only be one comment, and it might only be at the top of the file, stating the copyright.
Open-source developers are different. The code can, most of the time, be edited and distributed freely. Here, there might be comments.
Of course, there's the meme of instructors telling students to comment every single line of code:
function // function keyword
promptValue() // function name
{ // brace
var // assign
x // variable name
= // equals sign
prompt("foo"); // prompt function
alert(x); // alert it out
return // return keyword
0; // All OK
} // closing brace
promptValue // function name
(); // no arguments
Not only is this an eyesore to read, it's harder to understand. If you name variables and functions with descriptive names, then you can get rid of many comments.
A common misconception is: The more comments, the better. Actually, flooding code with comments will only make the code harder to read. If a lot of code needs comments, check that all the names are descriptive.
Another thing to note that people said in the comments is that a lot of software have separate documentation. You can explain the code here.
So some code isn't commented because it's self-explanatory, and some aren't commented because it's a secret.
I am attempting to use doxygen to comment my Qt5 classes, in particular the Q_PROPERTY macro in the same manner as the Qt5 documentation. This has the property commented, with accessors and notifier if needed. Now I can produce that using Nathan Osman's and Maxim Paperno's hints from How to doxygen comment Qt properties? however although they show the accessors and notifiers correctly, in Qt5 there is also a link back from the method documentation to the property, i.e. the documentation has a link from text() and setText() to the properties documentation, rather than having their own, which I cannot reproduce.
The doxygen config for these are:
"ALIASES += accessor=\\par Access functions:^^"
"ALIASES += notifier=\\par Notifier signal:^^"
The .h file has the following as property and public method declaration. The two % characters block a link from the property accessor documentation to the method documentation the same way as in Qt. Obviously I have left out a lot of unnecessary stuff from the code..
/*!
\property MyClass::text
\brief This property holds the classes's text.
By default, this property contains an empty string.
#accessor %text(void), %setText()
*/
Q_PROPERTY(QString text READ text WRITE setText)
QString text() const;
void setText(const QString& text);
private:
QString m_text;
The cpp code has the following definition
QString MyClass::text() const
{
return m_text;
}
void MyClass::setText(const QString& text)
{
m_text = text;
}
Is there any way to reproduce this with doxygen?
Right thanks #albert for that. I did mean accessor not accessors a slight bit of finger trouble. Doxygen version is 1.8.17.
I am using doxygen to document some of my custom classes, however in Qt 5.15.0, and 4.8 at least, the documentation as in doxygen consists of lists of properties/methods etc. followed by more detailed documentation.
If there is a property with accessors, then the method in the list section links to the property details, rather than a method detail. However I haven't found a way of making that link using doxygen. The method in the list section has no link.
There is also a problem with propertied methods with the same property name and accessor name not showing documentation for the method, if you write extra for method. I tried doing it that way earlier.
I work on a project which uses Google's closure compiler with advanced optimizations turned on. I would like to include moment.js in the compilation, however all of my attempts have been fruitless.
I have tried exporting the moment function, but there are still run time problems, and a some compile errors.
Has anyone successfully compiled moment.js with advanced optimizations, or know how to do so?
The only solution I can come up with, is to concatenate the minified file to the compiled source and use externs for every function I use from moment.js. But this is not an ideal solution.
I saw two issues with the code which would have to be corrected before momentjs would be compatible with ADVANCED_OPTIMIZATIONS. There may be more, but these were the glaring ones:
Using an alias for the prototype: All references to .fn would need to be replaced with .prototype.
Using a helper function to add methods: the extend method hides definitions from the compiler. All uses of the extend helper function would have to be refactored so that they do not hide the property assignments from the compiler.
I can't get it to work either as of 26 March 2015, but the existence of this suggests that it's possible. Here are the externs
You've gotta write your own externs file for moment.js for what you use from it (or the entire object, but I find that a bit of extra work for no reason).
For example, I've got this snippet to test if an input's date is within 14 days from now
$checkout.find('.date-input').on('input', /** #this {Element} */ function () {
const $this = $(this);
const Days = Number($this.attr('data-days'));
if (Days > 0 && moment(/** #type {string} */($this.val())).diff(moment(), 'days') < Days) {
$checkout.find('.date-warning').removeClass('d-none');
} else {
$checkout.find('.date-warning').addClass('d-none');
}
});
And the only way I'd get that to compile correctly with advanced mode is by creating this extern.
/**
* #fileoverview Externs for moment
*
* #externs
*/
/**
* #param {string=} date
* #constructor
* #return {!moment}
*/
function moment(date) {}
/**
* #param {!moment} m
* #param {string} unit
* #return {number}
*/
moment.diff = function (m, unit) {};
moment.prototype.diff = moment.diff;
Now clearly that description of the moment function isn't perfect; it's missing some parameters that the moment function has, but I'm not using them so it doesn't matter to me.
But that's how I start my externs. I start basic as the need arises and then I continue to grow the externs file with the more functions I need from a library.
And don't forget to tell Closure Compiler where your extern is located with the flag --externs 'externs/moment.js'.
I am trying to compile my code generated by browserify with Google Closure Compiler using Advanced Optimization.
Tried running browserify with different flags, no success so far.
Have any one have some experience with that?
I had to change the file: /node_modules/browserify/node_modules/browser-pack/_prelude.js with google closure annotations and add the externs files as
/**
* #param {*=}o
* #param {*=}u
*/
function require(o,u){}
What errors/warnings do you get?