When I define an entity with and provide a documentation for it:
/**
User Info:
* `event` - the corresponding event.
*/
static let eventNotification = Notification.Name(rawValue: "MSGameEvent")
Quick Help displays it wrong:
As you can see, the doc is split into two parts (Summary and Discussion) with the Declaration stuffed in the middle. This makes the documentation barely readable (and hurts my perfectionism).
How can I make the quick help continuous?
Related
In building my documentation I'm running into a lot of warning messages such as the following:
/home/X/Y/src/core/include/math/bigintntl/transformntl.h:92: warning: documented empty return type of NTL::NumberTheoreticTransformNtl::ForwardTransformToBitReverseInPlace. I'd like to turn off the specific warnings related to X is not documented. How might I go about doing so? I'm building the documentation of a rather large library, and until we have time to go back and update the docs, this just adds a lot of noise to our builds.
The documenting line:
/**
* In-place forward transform in the ring Z_q[X]/(X^n+1) with prime q and
* power-of-two n s.t. 2n|q-1. Bit reversing indexes. [Algorithm 1 in
* https://eprint.iacr.org/2016/504.pdf]
*
* #param &rootOfUnityTable is the table with the n-th root of unity powers in
* bit reverse order.
* #param &element[in,out] is the input/output of the transform of type VecType and length n.
* #return none
*/
void ForwardTransformToBitReverseInPlace(
const VecType& rootOfUnityTable, VecType* element);
from OpenFHE library
and the .rst file looks like the following (autodoxygenindex is a Breathe directive: https://breathe.readthedocs.io/en/latest/directives.html#autodoxygenindex):
Core Math Big Int NTL Documentation
=========================================
.. autodoxygenindex::
:project: core_math_bigintntl
while the conf.py file is here.
Looks like the issue for me was that breathe was regenerating the documentation because I was using a specific command. Unfortunately, this regeneration seemed to ignore the Doxyfile that was coming in. So, I had to manually pass in the relevant variables via breathe_doxygen_config_options See breathe config-values
I would like to know if there is a message I can override in Pharo so that my custom classes display more descriptive information in the inspector/debuger much like simple variable types do, like Integers or Strings. For instance:
Instead of that, I would like it to show a more custom and informative description consisting of its internal variales so as to have a tighter/tidier view of the variables instead of having to click on it and open another chart (therefore losing sight of the information on the previous chart). I know you can increase the amount of charts shown below, but that is not the point of the question. I would like to achieve something like this:
I have browsed the pharo forums and found nothing, I have also tried overriding over 30 methods hoping that one of them changed the output. Only the class message seemed to change the output, but I could only return an instance of Metaclass and besides messing with this message would break a lot of stuff. Finally I tried to reverse engineer the debugger and then the inspector to see at which point is the table constructed and what values are used or which messages are sent to build said values, but it was just too much for me, the callstack kept growing and I couldn't even scratch the surface.
Luckily, doing this in any Smalltalk is very easy. Types inherited from Object are expected to answer to the message printString, and ultimately printOn: aStream. Those messages are expected to give a description of the object. So, you should just override printOn: in your class (printString uses printOn:) and all the browsers and inspectors will automatically use it. There other possibilities in Pharo, if you want to provide more complex information in different tabs, but I think printOn: will suffice for you.
An example would be:
MyPoint>>printOn: aStream
aStream nextPut: ${.
x printOn: aStream.
aStream nextPutAll: ', '
y printOn: aStream.
aStream nextPut: $}
In Smalltalk, every time you observe something you don't like or understand, you ask the question: Which message is doing this?
In your case, the question would be: Which message creates the string a MyPoint that I see everywhere?
Next, to answer your question you need to find a good place for inserting a halt and then debug from there until you find the culprit. To do this just find the simplest expression that would reproduce the issue and debug it. In your case the right-click command in the Playground will do. So,
Write and select (MyPoint on: 14 and: -5) halt in a Playground.
Right-click and issue the Print it command (I'm assuming you already checked that this command produces the string 'a MyPoint').
Debug
Go over the evaluation of #DoIt, which answers the result
Continue this way alternating between Into and Over to make sure you follow the result to where it's being taken
Eventually you will reach the implementation of Object >> #printString. Bingo!
Now you can open a System Browser and take a look at this method, study how it's been implemented in different classes, etc. Your investigation should show you that the most basic message for printing is #printOn:. You may also want to take a look at other implementors so to better understand what people usually do. (Bear in mind that writing good #printOn:s is a minimalist art)
Overriding printOn: will work for simple cases where you want to just change description.
Pharo allows a lot more than that!
Due the extensible (moldable) nature of our inspector, you do not need to override a method to get your own visualisation of the object.
For example, look this array visualisation:
This is obtained adding this method to Collection:
gtInspectorItemsIn: composite
<gtInspectorPresentationOrder: 0>
^ composite fastList
title: 'Items';
display: [ self asOrderedCollection ];
beMultiple;
format: [ :each | GTObjectPrinter asTruncatedTextFrom: each ];
send: [ :result |
result
ifNil: [ nil ]
ifNotNil: [ result size = 1
ifTrue: [ result anyOne ]
ifFalse: [ self species withAll: result ]
]
]
if you browse for senders of gtInspectorPresentationOrder: you will see there are already a lot of special visualisations in the image.
You can take those as an example on how to create your own, adapted exactly to what you need :)
I have multiple todo items I want to add for a function.
What is the correct way to add them in a phpDoc comment block?
I understand that I should use the #todo tag.
But I am unsure of whether I should use a single #todo tag per item, or one #todo tag for the whole list.
Zero or more #todo tags is valid.
PSR-5: PHPDoc
Syntax
#todo [description]
Example
/**
* Counts the number of items in the provided array.
*
* #todo add an array parameter to count
*
* #return int Returns the number of elements.
*/
function count()
{
<...>
}
From the standard (emphasis mine):
The #todo tag is used to indicate that an activity surrounding the associated "Structural Elements" must still occur. Each [#todo] tag MUST be accompanied by a description that communicates the intent of the original author; this could however be as short as providing an issue number.
The way I read this paragraph, there may be multiple #todo tags (since the standard refers to "each" instead of "the" tag) and each tag represents a single incomplete behavior (since it reads "an activity", instead of "activities").
This, to me, makes the most sense, as each #todo acts as an item in an overall check list. As you complete an item, you "check it off" by deleting the todo item. This would appear very clearly as a line delete in your version control diffs.
However, these are simply annotations, so you may choose of course to ram multiple tasks into one.
In Visual Studio you can minimize huge chunks of code using regions; they essentially just surround the code and minimize it in the window.
Does Sublime have a feature similar to this?
By default, you can select some code the go to Edit > Code Folding > Fold. There are tons of plugins that leverage the code-folding api for more options.
There's a request on the official site to "ask for features" here.
But apparently:
FYI, Jon has stated that this is not possible in the current
implementation of the editor control. Looks like we're waiting till V3
guys.
Jon being the programmer behind Sublime Text 2.
There might be a way to fake it by creating a plugin that looks for markers and removes the code region in between the markers, but it probably wouldn't look good. With the current API, it's probably your best bet!
By the way, there is some code folding in Sublime Text, if you hover your mouse next to the line number, you will see some arrows appearing when you can fold / unfold.
I ended up using custom comment tags, indented one level less than the code I want to fold. It doesn't look best, though it serves its purpose.
class Foobar {
// ...some code
// <fold
function foo() {
}
function bar() {
}
// </fold
// more code...
}
This (at the moment) folds to:
class Foobar {
// ...some code
// <fold[...]
// </fold
// more code...
}
Having a native ST2 support for this would be nice.
This looks what you are looking for. You can define tags for #region and #endregion for each language, or a generic tag for all of them.
If you are obsessed with intendation, this solution may make you uncomfortable but here it is, once upon a time while I had been writing a semi-complex jQuery plugin I've had constants, variables, private and public functions sections and foldings like so;
;(function($, undefined, window) {...
/* Consts */
var FOO = "BAR";
/* Variables */
var m_Foo = "bar";
/* Functions */
/* Public Functions */
function foo() {...}
function bar() {...}
/* Private Functions */
function _foo() {...}
function _bar() {...}
})(jQuery, window);
As you can see it is all about intendation. Sections can be folded; Consts, Variables, Functions. And also inside Functions section, Public Functions and Private Functions are both can be folded.
You can also use one line comment (//) to name your fold. So the idea underneath that is simple; ST2 thinks that the more intended lines belongs to first less-intended comment above them, like C/C++ compilers how handle brackets as own unique code blocks.
To fold the code select the code and press
ctrl + shift + [
To unfold the code put the cursor there and press
ctrl + shift + ]
I think that like myself, the OP has come to appreciate a little-known feature in VS called regions that many equate to code-folding, but is FAR more powerful and above, Dio Phung provided the answer that I wanted, and I suspect the OP wanted, but he didn't share as an answer so here it is.
The difference between "code-folding" as it's provided in Sublime Text is that it's based on code/compiler syntax while "regions" and what this plugin does, allow you infinitely more freedom, though it's a freedom that's more or less dependant on the code you're working with to begin with (deeply nested, or properly modularized).
If you are on Sublime Text 3, here is a plugin that can do it :
github.com/jamalsenouci/sublimetext-syntaxfold – Dio Phung
In languages which support 3 types of comments (e.g. PHP) I use the hashtag comment for regions, as shown in the other answers. It's also good for keeping track of what's being done
# default options
$a = 3;
$b = 'bob';
$old_code = 1;
# bugfix #130
$result = magic_function($data);
fix_stuff($result);
$old_code = $result;
Otherwise use triple slash ///, or //# etc.
In sublime text, it works like this, it shades the lines you want to collapse and presses (Control + Shift +?)
I have the most recent version of sublimetext.
I have Адреса магазинов on page and want to store text, then click on this link and verify that the page where am I going to contains this text in headers. So I tried to find element by xpath, and selenium.getText get the right result, but selenium.click goes to another link. Where have I made a mistake? Thanks in advance!
String m_1 = selenium.getText("xpath=html/body/div[3]/div[2]/div[1]/h4[1]");
selenium.click("xpath=html/body/div[3]/div[2]/div[1]/h4[1]");
selenium.waitForPageToLoad("30000");
assertTrue(selenium.getText("css=h3").contains(m_1));
page:http://www.svyaznoy.ru/map/
Resume:
using xpath=//descendant::a[#href='/address_shops/'][2] or css=div.deff_one_column a[href='/address_shops/'] get right results
using xpath=//a[#href='/address_shops/'] - Element is not currently visible
xpath=//a[#href='/address_shops/'][2] - Element not found
There is a missing slash at the beginning of the expression. I am kind of surprised this got through at all - the first slash means "begin at root node".
Also, it is better to select the <a> element instead of the <h>. Sometimes it works, sometimes is misclicks, sometimes the click doesn't do anything at all. Try to be as concrete as you can be.
Try this one.
String m1 = selenium.getText("xpath=/html/body/div[3]/div[2]/div/h4/a");
selenium.click("xpath=/html/body/div[3]/div[2]/div/h4/a");
selenium.waitForPageToLoad("30000");
// your variable is named m1, but m_1 was used here
assertTrue(selenium.getText("css=h3").contains(m1));
By the way, there are even better XPath expressions you could use. See the documentation, it really is helpful. Just an example, this would work, too, and is much easier to write and read:
String m1 = selenium.getText("xpath=//a[#href='/address_shops/']");
selenium.click("xpath=//a[#href='/address_shops/']");
Sorry, didn't notice page link. Css for second link can be something like that css=div.deff_one_column a[href='/address_shops/']