I am looking to have JSON examples in my documentation, which in turn will have JSON examples in my intellisense for VScode.
I have tried every trick in the book that I can think of, is this possible to do with line breaks and things that would make the JSON readable? I cannot get this to work in VScode no matter what I do, it takes out white space and makes one line.
I try to do:
/**
* {
* "JSONData":"not going to format like this"
* }
*/
functionToDescribe()
this of course will end up in intellisense like so...
{ "JSONData":"not going to format like this" }
This is ok with small examples, but I would like to have a bit larger (still small) simple examples. There are other reasons I really want line breaks, not just JSON, I just want my text to be cleaner in my comments in general.
I will also take different examples of how other people document it. I am really looking to make my JS code easier to know what to expect the function to accept, return and use in operation before using it.
EDIT:
I stumbled across this link: https://github.com/Microsoft/vscode/issues/30062
which now I understand that formatting works when you look at the declaration of the function or item, but not when you go to use it.
the following markup code works great when I hover over the function name, but when I use it like normal it is all on one line and worthless
/** This is a description
* with each line
* on it's own
*
* #example Test
* ```javascript
* let valueReturned = false;
* jest.fn(() => {
* if (!valueReturned) {
* valueReturned = true;
* return value;
* //no idea why it requires me to have so many spaces...
* }
* });
* ```
*/
functionTest() //When hovering over this, it looks great
functionTest( //at this point intellisense pops up and is worthless
I believe this is a bug or simply bad design, maybe I will put in a feature request, if it doesn't already exist.
I will keep this question open in case someone else has any suggestions or possible work arounds.
EDIT:
Good news, it looks like this was a bug and after searching for quite a while, it seems this was fixed just this month and will be with the September release!
https://github.com/Microsoft/vscode/issues/1920
I will close this now and leave this up for anyone else who was having troubles with this.
This was a bug for the intellisense, which has been corrected as of 4 days ago, so it should be released soon, so if you can get the "hover" to look as you want, it should translate to the intellisense when the fix drops.
https://github.com/Microsoft/vscode/issues/1920
Related
I am working on a VsCode extension in that I want to provide custom snippets for code completion.
I know about the option of using snippet json files directly, however those have the limitation of not being able to utilize the CompletionItemKind property that determines the icon next to the completion suggestion in the pop-up.
My issue:
If I implement a simple CompletionItemProvider like this:
context.subscriptions.push(
vscode.languages.registerCompletionItemProvider(
{scheme:"file",language:"MyLang"},
{
provideCompletionItems(document: vscode.TextDocument, position: vscode.Position) {
let item = new vscode.CompletionItem('test');
item.documentation = 'my test function';
item.kind = vscode.CompletionItemKind.Function;
return [item];
}
}
)
)
then the original VsCode IntelliSense text suggestions are not shown anymore, only my own. Should I just return a kind of an empty response, like
provideCompletionItems(document: vscode.TextDocument, position: vscode.Position) {
return [null|[]|undefined];
}
the suggestions appear again as they should. It seems to me that instead of merging the results of the built-in IntelliSense and my own provider, the built-in ones get simply overridden.
Question:
How can I keep the built-in IntelliSense suggestions while applying my own CompletionItems?
VsCode Version: v1.68.1 Ubuntu
I seem to have found the answer for my problem, so I will answer my question.
Multiple providers can be registered for a language. In that case providers are sorted
by their {#link languages.match score} and groups of equal score are sequentially asked for
completion items. The process stops when one or many providers of a group return a
result.
My provider seems to provide results that are just higher scored than those of IntelliSense.
Since I didn't provide any trigger characters, my CompletionItems were comteping directly with the words found by the built-in system by every single pressed key and won.My solution is to simply parse and register the words in my TextDocument myself and extend my provider results by them. I could probably just as well create and register a new CompletionItemProvider for them if I wanted to, however I decided to have a different structure for my project.
Firstly, Karate UI automation is really awesome tool. I am kind of enjoying it while writing the UI tests using Karate. I ran into a situation where in, i was trying to fetch the shadowRoot elements. I read few similar posts related to javascript executor with karate and learnt that it is already answered. it is recommended to use driver.eval. But in Karate 0.9.5 there is no eval, it has script() or scriptAll(). I have gone through documentation couple of times to figure out how i can fetch element inside an element but no luck.
Using traditional selenium+java, we can fetch shadowRoot like this way:
something like shadowRoot which sits inside a parent element like div or body.
//downloads-manager is the tagname and under that downloads-manager, a shadowRoot element exists
The HTML looks like this. it is from chrome://downloads.
<downloads-manager>
#shadow-root(open)
</download-manager>
WebElement downloadManager =driver.findElement(By.tagName("downloads-manager");
WebElement shadowRoot= (WebElement)((JavaScriptExecutor)driver)
.executeScript("return arguments[0].shadowRoot",downloadManager);
So i tried the following in Karate UI
script("downloads-manager","return _.shadowRoot"); //js injection error
script('downloads-manager', "function(e){ return e.shadowRoot;}"); // same injection error as mentioned above.
def shadowRoot = locate("downloads-manager").script("function(e){return e.shadowRoot};"); //returns an empty string.
I bet there is a way to get this shadowRoot element using Karate UI but i am kind of running out of options and not able to figure out this.
Can someone please look into this & help me?
-San
Can you switch to XPath and see if that helps:
* def temp = script('//downloads-manager', '_.innerHTML')
Else please submit a sample in this format so we can debug: https://github.com/intuit/karate/tree/develop/examples/ui-test
EDIT: after you posted the link to that hangouts example in the comments, I figured out the JS that would work:
* driver 'http://html5-demos.appspot.com/hangouts'
* waitFor('#hangouts')
* def heading = script('hangout-module', "_.shadowRoot.querySelector('h1').textContent")
* match heading == 'Paul Irish'
It took some trial and error and fiddling with the DevTools console to figure this out. So the good news is that it is possible, you can use any JS you need, and you do need to know which HTML element to call .shadowRoot on.
EDIT: for other examples of JS in Karate: https://stackoverflow.com/a/60800181/143475
I've been setting up a site with Wintersmith and am loving it for the most part, but I cannot wrap my head around some of the under-the-hood mechanics. I started with the "blog" skeleton that adds the paginator.coffee plugin.
The question requires some details, so up top, what I'm trying to accomplish:
Any files (markdown, html, json metadata) will be picked up either in /contents/article/<file> or /contents/articles/<subdir>/<file>
Output files are at /articles/YYYY/MM/DD/title-slug/
/blog.html lists all articles, paginated.
Files just under /contents (not in articles) are not treated as blog posts. Markdown and JSON metadata are still processed, but no permalinked URLs, not included in blog listings, file/directory structure is more directly copied over.
So, I solved #1 with this suggestion: How can I have articles in Wintersmith not in their own subdirectory? So far, great, and #3 is working -- the paginated listing includes all posts. #4 has not been an issue, it's the default behavior.
On #2 I found this solution: http://andrewphilipclark.com/2013/11/08/removing-the-boilerplate-from-wintersmith-blog-posts/ . As the author mentions, his solution was (sort of) subsequently incorporated into Wintersmith master, so I tried just setting the filenameTemplate accordingly. Unfortunately this applies to all content, not just that under /articles, so the rest of my site gets hosed (breaks #4). So then I tried the author's approach, adding a blogpost.coffee plugin using his code. This generates all the files out of /contents/articles into the correct permalink URLs, however the paginator now for some reason will no longer see files directly under /articles (point #1).
I've tried a lot of permutations and hacking. Tried changing the order of which plugin gets loaded first. Tried having PaginatorPage extend BlogpostPage instead of Page. Tried a lot of things. I finally realize, even after inspecting many of the core classes in Wintersmith source, that I do not understand what is happening.
Specifically, I cannot figure out how contents['articles']._.pages and .directories are set, which seems relevant. Nor do I understand what that underscore is.
Ultimately, Jade/CoffeeScript/Markdown are a great combo for minimizing coding and enhancing clarity except when you want to understand what's happening under the hood and you don't know these languages. It took me a bit to get the basics of Jade and CoffeeScript (Markdown is trivial of course) enough to follow what's happening. When I've had to dig into the wintersmith source, it gets deeper. I confess I'm also a node.js newbie, but I think the big issue here is just a magic framework. It would be helpful, for instance, if some of the core "plugins" were included in the skeleton site as opposed to buried in node_modules, just so curious hackers could see more quickly how things interconnect. More verbose docs would of course be helpful too. It's one thing to understand conceptually content trees, generators, views, templates, etc., but understanding the code flow and relations at runtime? I'm lost.
Any help is appreciated. As I said, I'm loving Wintersmith, just wish I could dispel magic.
Because coffee script is rubbish, this is extremely hard to do. However, if you want to, you can destroy the paginator.coffee and replace it with a simple javascript script that does a similar thing:
module.exports = function (env, callback) {
function Page() {
var rtn = new env.plugins.Page();
rtn.getFilename = function() {
return 'index.html';
},
rtn.getView = function() {
return function(env, locals, contents, templates, callback) {
var error = null;
var context = {};
env.utils.extend(context, locals);
var buffer = new Buffer(templates['index.jade'].fn(context));
callback(error, buffer);
};
};
return rtn;
};
/** Generates a custom index page */
function gen(contents, callback) {
var p = Page();
var pages = {'index.page': p};
var error = null;
callback(error, pages);
};
env.registerGenerator('magic', gen);
callback();
};
Notice that due to 'coffee script magic', there are a number of hoops to jump through here, such as making sure you return a buffer from getView(), and 'manually' overriding rather than using the obscure coffee script extension semantics.
Wintersmith is extremely picky about how it handles these functions. If callbacks are not invoked, for the returned value is not a Stream or Buffer, generated files will appear in the content summary, but not be rendered to disk during a build. Enable verbose logging and check of 'skipping foo' messages to detect this.
I'm working on a sample app for Facebook, using Flash Builder and Flex.
Now, I've got everything up and running - but there's one problem, specifically with the work history part.
When I try to display the user's work history..here's the code for logging in:
protected function login():void
{
FacebookDesktop.login(loginHandler, ["user_birthday", "user_work_history"]);
}
Here, loginHandler's a callback function, that then goes ahead and displays data about the user:
protected function loginHandler(success:Object,fail:Object):void
{
if (success){
currentState = "LoggedIn";
fname.text = success.user.name;
userImg.source=FacebookDesktop.getImageUrl(success.uid,"small");
birthdayLbl.text=success.user.birthday;
workLbl.text=success.user.work;
}
}
Now, the problem occurs with success.user.work - it ends up printing the following:
[object,Object],[object,Object],[object,Object],[object,Object]
Obviously, I'm doing something wrong..but I can't figure out what exactly it is. Would be grateful for some pointers!
Thanks!
Rudi.
The object contained in success.user.work is most likely an array of objects, each item representing a work period, so you'll have to treat it as such. Either use a list and a custom renderer for each item, or create a string by iterating over the array, and appending the fields that you're interested in.
To see what the individual objects contain, either use a breakpoint during debug and inspect them, or check to see if they're documented in the facebook development documentation.
I'm a Perl programmer for a long time, but I always have problems with documentation in POD.
When I use POD comments in the code, the code is difficult to read. When I use POD comments at the end of file, there is the danger that the documentation is not in sync with the code.
I miss a documentation style similar to Java.
/**
* #description
* ...
*/
I look for an easier and more intuitive documentation style. Is there such a thing?
A quick search found Doxygen Filter which purports to allow you to use Doxygen style comments (which are very close to Javadoc) to document Perl code.
Well, POD's the accepted standard for publishing Perl documentation.
I do find it rather annoying to maintain as well; I've recently experimented with using Pod::Weaver to maintain the documentation and build it into Pod on release. It's a little bit tricky in that it's quite flexible in how you filter and build the POD, and could do with a little more documentation (in POD or otherwise). But seems promising. Still too early for me to give more of a judgement than that, but it seems promising.
Hope this helps
Why do you think the code is hard to read with Pod? Is the code hard to read with other code around it? Perhaps you're putting too much into a particular part of the code, instead of writing small methods, etc. Are you sure it's not your code that's hard to read?
You don't have to put all of your documentation at the end of the code. Pod is perfectly fine inline with code, allowing you to put the documentation for a subroutine or method right next to the subroutine or method.
Is there some other problem you have with Pod?
The only time I have had a problem with POD is when using a text editor that doesn't highlight it correctly.
Just like everything in Java this seems overly verbose:
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute
{#link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
*
#param url an absolute URL giving the base location of the image
*
#param name the location of the image, relative to the url argument
*
#return the image at the specified URL
*
#see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
When compared to the equivalent Perl.
=item getImage( url, name )
This method always returns immediately, whether or not the
image exists. When this applet attempts to draw the image on
the screen, the data will be loaded. The graphics primitives
that draw the image will incrementally paint on the screen.
url must be an absolute URL giving the base location of the image
name is the location of the image, relative to the url argument
=cut
sub getImage{
my ($url,$name) = #_;
...
}
You might want to take a look at Rinci. Examples of applications which use this: File::RsyBak, Git::Bunch, App::OrgUtils.
Here's how you document modules. You declare %SPEC in your module and put documentation inside it. Each function gets its own key. There are predefined fields. Localization is supported. The formatting is done in Markdown. An example:
$SPEC{':package'} = {
summary => 'Module to do foo',
"summary.alt.lang.id_ID" => "Modul untuk melakukan foo",
description => <<EOT,
Blah...
...
EOT
links => [...],
};
$SPEC{func1} = {
summary => '...',
description => '...',
args => {
arg1 => {
schema => ...,
summary => ....,
description => ...,
},
},
examples => [...],
links => [...],
...
};
Instead of using Java- or Perl 5 style of putting documentation in "comments", it uses data structure directly available to the programs. (Note that Perl 6 is also going this way.) Think of it as Python docstring gone crazy (or structured).
There are tools to generate POD, text, HTML from the metadata (spec). Aside from documentation, the metadata is also useful for other things like argument validation, command-line interface, etc.
Disclosure: I'm the developer.
Myself, I often find wanting to reproduce code entries to documentation.
Yet to find how I can trick POD to read the code when podding whilst letting the code execute whilst parsing.
Do I really have to settle for this:
=head1 Variables
use vars (%V &C)
=cut
use vars (%V %C)
=head2 Constants
$C{hashConstant1} = "/path/to/file"
=cut
$C{hashConstant1} = "/path/to/file";
=head2 Variables
$V{strVar1} = undef
=cut
$V{strVar1} = undef;
Then again, most languages require the double typing to document.