I have few functions, that should be described in doxygen where 80% of description is the same.
I can copy-paste it over them, but sometimes this description is changing, and supporting changes in all those functions is becoming headache.
Is there a way in doxygen to create a named text block, that will be typed just once, and each function will be able to use it?
Something like that:
//! /textblock <supername> that is the text that I would like to have just once, but that should appears in different places in documentation
...
//! my function 1. /useblock <supername>. Just as it is.
void func1() { return; }
...
//! my function 2. /useblock <supername>. Yeah, make sense.
void func2() { return; }
...
//! my function 3. /useblock <supername>. Such great it is.
void func3() { return; }
I've used the "alias" custom command in doxygen for implementing "snippets". See http://www.doxygen.nl/manual/custcmd.html. Although the explanation makes it look like you can use this only for function-type things, it's great for repeated text.
Related
I want to create an "extension" for a Jacada Interaction (to extend functionality), in my case to parse and assign the numerical part of serialNumber (a letter, followed by digits) to a numeric global ("system") variable, say serialNumeric. What I am lacking is the structure and syntax to make this work, including the way to reference interaction variables from within the extension.
Here is my failed attempt, with lines commented out to make it innocuous after failing; I think I removed "return page;" after crashing, whereupon it still crashed:
initExtensions("serialNumeric", function(app){
app.registerExtension("loaded", function(ctx, page) {
// Place your extension code here
//$('[data-refname="snum"]').val('serialNumber');
// snum = Number(substring(serialNumber,1))
});
});
Here is an example of one that works:
/**
* Description: Add swiping gestures to navigate the next/previous pages
*/
initExtensions("swipe", function(app) {
// Swipe gestures (mobile only)
app.registerExtension('pageRenderer', function(ctx, page) {
page.swipe(function(evt) {
(evt.swipestart.coords[0] - evt.swipestop.coords[0] > 0)
? app.nextButton.trigger('click')
: app.backButton.trigger('click')
});
return page;
});
});
After reading the comment below, I tried the following, unsuccessfully (the modified question variable is not written back to that variable). It rendered poorly in the comment section, so I am putting it here:
initExtensions("serialNumeric", function(app){
app.registerExtension("loaded", function(ctx, page) {
var sernum = new String($('[data-refname="enter"] input'));
var snumeric = new String(sernum.substr(1));
$('[data-refname="enter"] input').val(snumeric);
});
});
I would like to understand when this code will run: it seems logical that it would run when the variable is assigned. Thanks for any insight ~
In your case, you extend loaded event. You don't have to return the page from the extension like in your working example below.
The page argument contains the DOM of the page you have just loaded, the ctx argument contains the data of the page in JSON form. You can inspect the content of both arguments in the browser's inspection tools. I like Chrome. Press F12 on Windows or Shift+Ctrl+I on Mac.
The selector $('[data-refname="snum"] input') will get you the input field from the question with the name snum that you defined in the designer. You can then place the value in the input field with the value from the serialNumber variable.
$('[data-refname="snum"] input').val(serialNumber);
You can also read values in the same way.
You can't (at this point) access interaction variables in the extension, unless you place theses variables inside question fields.
Here is a simple example how to put your own value programmatically into a input field and cause it to read it into the model, so upon next it will be sent to the server. You are welcome to try more sophisticated selectors to accommodate for your own form.
initExtensions("sample", function(app){
app.registerExtension("loaded", function(ctx, page) {
// simple selector
var i = $('input');
// set new value
i.val('some new value');
// cause trigger so we can read into our model
i.trigger('change');
});
});
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 adding a TinyMCE editor to one of our pages. For reasons above my pay-grade, we're using TinyMCE 3.5.4.1.
It's gone pretty well, except when I try to wire in an onFocus event handler. If I don't try to use the handler, the editors show up and work fine but on pages where I define a handler, there are boatloads of exceptions inside TinyMCE for the browser types I've tried (IE8,9,10 and Chrome).
I've been using templates from other posts I've seen on here but I haven't seen mention of all these TinyMCE exceptions. Of course, trying to unwind the minified script is a real pain.
The first example I found here had a setup function in the TinyMCE config like this:
, setup: function (ed) {
ed.onInit.add(function (ed, evt) {
if (!myFocus) return; // global for the handler to use
var dom = ed.dom;
var doc = ed.getDoc();
tinymce.dom.Event.add(doc, 'focus', myFocus);
});
}
When myFocus is defined, there are a number of exceptions TinyMCE throws starting with
if (j.isIE){l.attachEvent(...)} complaining that l.attachEvent doesn't exist. Then it moves on to all kinds of variable type mismatches.
Chrome developer tools are much more awkward fiddling with minified code, so I'm not sure what all it doesn't like.
Another post I found here suggested doing some minimal browser detection but this helped neither IE nor Chrome.
var doc = s.content_editable ? ed.getBody() : (tinymce.isGecko ? ed.getDoc() : ed.getWin())
Another post suggested a different approach, but I still had all the same errors in both browsers.
, setup: function (ed) {
ed.onInit.add(function (ed, evt) {
if (!myFocus) return;
ed.onFocus.add(myFocus);
});
}
I've also just tried (in vain)
, setup: function (ed) {
if (!myFocus) return;
ed.onFocus.add(myFocus);
}
Is event handling in TinyMCE just very fragile? Not well supported across browsers? Should I just steer clear of it and try using jQuery or something else?
Thanks
Mark
Turns out to be a pilot-error bug being deferred until the extend calls created the editor.
I am using jQuery 1.9.1.
Suppose i have a button with id="clickMe"
My jQuery code is:
$('#clickMe').click(function(event)
{
eventHandler1();//do something
eventHandler2();//use output from eventHandler1() and do something
}
Now, i want "eventHandler2" to be executed at last so that i could use the output of "eventHandler1". Is there any way to do this manually and not just the way i have put the handlers inside the click event?
One more thing, "eventHandler1()" and "eventHandler2()" are present in different .js files and thus the requirement.
jQuery.when() provides a way to execute callback functions based on one or more objects, usually Deferred objects that represent asynchronous events.
For example, when the Deferreds are jQuery.ajax() requests, the arguments will be the jqXHR objects for the requests, in the order they were given in the argument list.
$.when(eventHandler1).then(eventHandler2).done(function(){
alert('done.');
});
So can even use GLOBAL variable to store eventHandler1 output and access that inside eventHandler2
Example
var someVar;
function eventHandler1()
{
// process
someVar = some value from process
return someVar;
}
function eventHandler2()
{
alert(someVar);
}
Response to OP comment
as you have asked about execute handler in queue you can use Jai answer.
you can use .when .then and .done as below.
$.when(eventHandler1).then(eventHandler2).done(function(){
//process code
});
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.