I have a .clang-format with ColumnLimit: '80'. When I write doxygen blocks for functions like the following, they get neatly wrapped at 80 characters:
/**
* #brief Writes out the 80-byte header (in binary STL) for the STL representation of some geometry.
* #param[out] fileStream - The file to write the header to
*/
Becomes:
/**
* #brief Writes out the 80-byte header (in binary STL) for the STL
* representation of some geometry.
* #param[out] fileStream - The file to write the header to
*/
But if I do the same thing with \ instead of # it no longer automatically wraps if it goes over:
/**
* \brief Writes out the 80-byte header (in binary STL) for the STL representation of some geometry.
* \param[out] fileStream - The file to write the header to
*/
I should note that the following lines after a \, or just stray comment blocks work fine. IE, if I do
/**
* Here is a really long comment that is greater than 80 characters, notice how it gets wrapped?
*/
It becomes:
/**
* Here is a really long comment that is greater than 80 characters, notice
* how it gets wrapped?
*/
Why does this happen?
Clang version: 7.0.1
My IDE is QTCreator, version 4.7.2. I have it set to reformat files on saving them, which it does for everything. (Except comment lines starting with \)
Related
I am trying to do this:
/**
#param argumentString This is a multiline
comment
about
argumentString
*/
- (void)doSomething:(NSString *)argumentString;
But I don't think #param supports multiple lines describing the same parameter. I haven't been able to find out a way to do this yet; my end goal is to make all the text appear in the same section in the correct segment. With the above code the comment about argumentString part will be moved to the Description section instead. I've tried using #parblock but it doesn't seem to work.
It is very easy to do in Swift, but for Objective-C, there's a simple hack which can make a parameter description look like it is in multiple lines.
Simply add another param whose first word is a whitespace unicode character (other than space). In the following example, I have copied the unicode U+2007 in the 2nd line.
/**
This is the description
#param argumentString: This is a comment,
#param which looks like a multiline comment
*/
- (void)doSomething:(NSString *)argumentString;
The second #param line in the example above is effectively this:
#param U+2007 <space> <comment-text>
The unicode which you could copy is :
Result
This is how it renders in Xcode:
Try this:
/**
* #param argumentString This is a multiline
* comment
* about
* argumentString
*/
What is the maximum number of characters that could be output from the Win32 functions ToUnicode()/ToAscii()?
Surely there is a sensible upper bound on what it can output given a virtual key code, scan key code, and keyboard state?
On my Windows 8 machine USER32!ToAscii calls USER32!ToUnicode with a internal buffer and cchBuff set to 2. Because the output of ToAscii is a LPWORD and not a LPSTR we cannot assume anything about the real limits of ToUnicode from this investigation but we know that ToAscii is always going to output a WORD. The return value tells you if 0, 1 or 2 bytes of this WORD contains useful data.
Moving on to ToUnicode and things get a bit trickier. If it returns 0 then nothing was written. If it returns 1 or -1 then one UCS-2 code point was written. We are then left with the strange 2 <= return expression. We can try to dissect the MSDN documentation:
Two or more characters were written to the buffer specified by pwszBuff. The most common cause for this is that a dead-key character (accent or diacritic) stored in the keyboard layout could not be combined with the specified virtual key to form a single character. However, the buffer may contain more characters than the return value specifies. When this happens, any extra characters are invalid and should be ignored.
You could interpret this as "two or more characters were written but only two of them are valid" but then the return value should be documented as 2 and not 2 ≤ value.
I believe there are two things going on in that sentence and we should eliminate what it calls "extra characters":
However, the buffer may contain more characters than the return value specifies.
This just implies that the function may party on your buffer beyond what it is actually going to return as valid. This is confirmed by:
When this happens, any extra characters are invalid and should be ignored.
This just leaves us with the unfortunate opening sentence:
Two or more characters were written to the buffer specified by pwszBuff.
I have no problem imagining a return value of 2, it can be as simple as a base character combined with a diacritic that does not exist as a pre-composed code point.
The "or more" part could come from multiple sources. If the base character is encoded as a surrogate-pair then any additional diacritic/combining-character will push you over 2. There could simply also be more than one diacritic/combining-character on the base character. There might even be a leading LTR/RTL mark.
I don't know if it is possible to end up with all 3 conditions at the same time but I would play it safe and specify a buffer of 10 or so WCHARs. This should be well within the limits of what you can produce on a keyboard with "a single keystroke".
This is by no means a final answer but it might be the best you are going to get unless somebody from Microsoft responds.
In usual dead-key case we can receive one or two wchar_t (if key cannot be composed with dead-key it returns two whar_t's) for one ToUnicode call.
But Windows also supports ligatures:
A ligature in keyboard terminology means when a single key outputs two or more UTF-16 codepoints. Note that some languages use scripts that are outside of the BMP (Basic Multilingual Plane) and need to be completely realized by ligatures of surrogate pairs (two UTF-16 codepoints).
If we want to look from a practical side of things: Here is a list of Windows system keyboard layouts that are using ligatures.
51 out of 208 system layouts have ligatures
So as we can see from the tables - we can have up to 4 wchar_t for one ToUnicode() call (for one keypress).
If we want to look from a theoretical perspective - we can look at kbd.h in Windows SDK where underlying keyboard layout structures are defined:
/*
* Macro for ligature with "n" characters
*/
#define TYPEDEF_LIGATURE(n) typedef struct _LIGATURE##n { \
BYTE VirtualKey; \
WORD ModificationNumber; \
WCHAR wch[n]; \
} LIGATURE##n, *KBD_LONG_POINTER PLIGATURE##n;
/*
* Table element types (for various numbers of ligatures), used
* to facilitate static initializations of tables.
*
* LIGATURE1 and PLIGATURE1 are used as the generic type
*/
TYPEDEF_LIGATURE(1) // LIGATURE1, *PLIGATURE1;
TYPEDEF_LIGATURE(2) // LIGATURE2, *PLIGATURE2;
TYPEDEF_LIGATURE(3) // LIGATURE3, *PLIGATURE3;
TYPEDEF_LIGATURE(4) // LIGATURE4, *PLIGATURE4;
TYPEDEF_LIGATURE(5) // LIGATURE5, *PLIGATURE5;
typedef struct tagKbdLayer {
....
/*
* Ligatures
*/
BYTE nLgMax;
BYTE cbLgEntry;
PLIGATURE1 pLigature;
....
} KBDTABLES, *KBD_LONG_POINTER PKBDTABLES;
nLgMax here - is a size of a LIGATURE##n.wch[n] array (affects the size of each pLigature object).
cbLgEntry is a number of pLigature objects.
So we have a BYTE value in nLgMax - and that meant that ligature size could be up to 255 wchar_t's (UTF-16 code points) theoretically.
The documentation for namepaths says you should escape special characters:
Above is an example of a namespace with "unusual" characters in its
member names (the hash character, dashes, even quotes). To refer to
these you just need quote the names: chat."#channel",
chat."#channel"."op:announce-motd", and so on. Internal quotes in
names should be escaped with backslashes:
chat."#channel"."say-\"hello\""
However, this doesn't work on dots. If I have an event called "cellClick.dt" that I want to document, jsDoc skips the documentation from the output, and generates an incorrect link in the table of contents. I have tried the following combinations:
myClass~event.namespace
'myClass~event.namespace'
myClass~event\.namespace
myclass~'event.namespace'
All of them generate broken docs in some way. The last one at least seem to generate correct links and docs, but the apostrophes are still here in the output. This makes it very cumbersome to document code that uses dots for namespace separators in events (like eg. jQuery plugins do by default).
What's the correct way to do this? Is there one? The version I'm using is 3.3.0-alpha9.
I would suggest doing this:
/**
* #class
*/
function myClass () {
}
/**
* #memberof myClass
* #event event.namespace
*/
The event is properly named and is a member of myClass. It's annoying to have to split off the full name in two parts but at least the result is not ugly.
Note: When I'm describing /** ... */ comment blocks, I'm referring to the following types of comment blocks
/**
* This is a comment block that
* spans multiple lines.
*
* Each line is prefixed with a "\t* " string
*/
I'm used to the very automated commenting of comment blocks in IDEs, but it doesn't seem that vim supports these kinds of comments too well.
Specifically, I'm looking for this kind of automated functionality. Say you have the following comment
/**
* This is a comment and I plan to run to the next line.
In vim's insert mode, when my cursor is at the period and I hit "enter", I want another "\t* " string to be placed on the new line.
Furthermore, when I hit "/" to end the comment block on a brand new line starting with "\t* ", it would delete the space and place "/" on this new line.
For example, if I have
/**
* This is a comment and I plan to run to the next line.
*
(with a space after the '*' character), and I hit "/", I should produce
/**
* This is a comment and I plan to run to the next line.
*/
Any plug in or vimscript that would help me support this?
Note that I've looked at the nerd commenter already, but the comments created by the nerd commenter don't seem automated (ie: I have to press a keystroke or two to activate commenting.)
Also, whenever I make block comments, I always start with "/**".
Vim can do this by itself. Just add
filetype plugin indent on
to your vimrc.
After this is done the defualt ftplugins should enable it for you. If it doesn't I believe adding to ~/.vim/after/ftplugin/{filetype}.vim
setlocal formatoptions+=r
should enable it.
/* Suppose I have a multi-line comment with hard line-breaks
* that are roughly uniform on the right side of the text,
* and I want to add text to a line in order to make the
* comment a bit more descriptive.
*/
Now, most unfortunately, I need to add text to one of the top lines.
/* Suppose I have a multi-line comment with hard line-breaks (here is some added text for happy fun time)
* that are roughly uniform on the right side of the text,
* and I want to add text to a line in order to make the
* comment a bit more descriptive.
*/
It takes O(n) time (n being the number of lines) to fix each line so that they roughly line up again. The computer should do this, not me.
Are there tools to deal with this in our IDEs? What are they called?
emacs supports the command fill-paragraph which is typically mapped to meta-q.
Output from fill-paragraph on your second paragraph of text:
/* Suppose I have a multi-line comment with hard line-breaks (here is
* some added text for happy fun time) that are roughly uniform on the
* right side of the text, and I want to add text to a line in order
* to make the comment a bit more descriptive.
*/
Eclipse has this built in (at least, I think it's what you want). When you type a comment, you then type Ctrl+Shift+F and it will format either all your code, or just the section of code that you have highlighted.
I just tested it now and it aligned all my comments for me.