When looking at the source code of Angular it seems there is a certain way how to style the comments. A quick google search does not reveal what rules to follow. What are the guidelines?
For example, a comment for a function looks like this:
/**
* when using forEach the params are value, key, but it is often useful to have key, value.
* #param {function(string, *)} iteratorFn
* #returns {function(*, string)}
*/
function reverseParams(iteratorFn) {
return function(value, key) { iteratorFn(key, value); };
}
It starts with a slash (/) and followed by two two asterisks (*) and it has an asterik on every line. Where is that defined? And then there are several #-symbols. Javascript comments starts with /* or //, as described here, so there are some additional styling involved here. I am searching for a description on this....
Ok, I am going to answer this myself. Somebody gave me this link in a comment of an answer that is now deleted. Thanks to you, whoever you are. I am cutting and pasting from this doc:
A doc comment is written in HTML and must precede a class, field, constructor or method declaration. It is made up of two parts -- a description followed by block tags. In this example, the block tags are #param, #return, and #see.
/**
* 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;
}
}
Notes:
The resulting HTML from running Javadoc is shown below
Each line above is indented to align with the code below the comment.
The first line contains the begin-comment delimiter ( /**).
Starting with Javadoc 1.4, the leading asterisks are optional.
Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).
Notice the inline tag {#link URL}, which converts to an HTML hyperlink pointing to the documentation for the URL class. This inline tag can be used anywhere that a comment can be written, such as in the text following block tags.
If you have more than one paragraph in the doc comment, separate the paragraphs with a paragraph tag, as shown.
Insert a blank comment line between the description and the list of tags, as shown.
The first line that begins with an "#" character ends the description. There is only one description block per doc comment; you cannot continue the description following block tags.
The last line contains the end-comment delimiter ( */) Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk.
For more examples, see Simple Examples.
So lines won't wrap, limit any doc-comment lines to 80 characters.
Here is what the previous example would look like after running the Javadoc tool:
getImage
public Image getImage(URL url,
String name)
Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument.
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.
Parameters:
url - an absolute URL giving the base location of the image.
name - the location of the image, relative to the url argument.
Returns:
the image at the specified URL.
See Also:
Image
After seeing this post I tried typing '/**' and I got this in vs code editor
Hit enter and I got like this
however, I don't know whether it is given from vs code extension. I think it is a standard way to comment.
Related
I'm trying to create a page type hierarchy where I can use it both a page hierarchy as well as props and evars, using the page URL. In a nutshell my URL would look something like this:
http://www.domain.com/BrandHomePage/SuperCategory/ProductCategory/Product
The mindset is to take the URL and use a data element to split the URL, and then capture the values into separate data elements that could also be used in a page hierarchy.
var url = "http://www.domain.com/part1/part2/part3/part4"
var parts = url.split('/').splice(2);
console.log(parts);
var baseUrl = parts[0];
var part1 = parts[1];
var part2 = parts[2];
var part3 = parts[3];
var part4 = parts[4]
My question is, would it even be possible to capture each individual portion of the URL into separate data elements? Or is my approach overkill.
Create a Data Element
The following will create a Data Element that returns an array containing up to 4 elements, depending on how many dir levels there are in the URL.
Go to Rules > Data Elements > Create New Data Element
Name it "hier1" (no quotes).
Choose Type Custom Script and click Open Editor.
Add the following code to the code box:
return location.pathname.split('/').filter(Boolean).slice(0,4);
When you are done, Save Changes.
Populate the Hierarchy Variable
Here is an example of populating hier1 on page view.
Go to Overview > Adobe Analytics Tool Config > Pageviews & Content
Under Hierarchy, select Hierarchy1 from the dropdown (this is shown by default).
To the right of the dropdown, in the first field, add %hier1%
Leave the other 3 fields blank.
Leave Delimiter as default comma , (it doesn't matter what you put here).
Note: DTM stringifies the returned array (String(Array) or Array.toString()) from the Data Element, which is effectively the same as doing Array.join(','). This is why the above shows to only put the Data Element reference in the first field, and the Delimiter is ignored.
If your implementation uses a delimiter other than a comma, see additional notes below.
Additional Notes
Populating other Variables
You can also reference %hier1% to populate other variable fields in the Global Variables section. Note that the data element will be stringified with default comma delimiter.
Alternatively, you may consider using Dynamic Variable syntax (e.g. D=h1) as the value, to shorten the request URL. If you are using the latest AppMeasurement and Marketing Cloud Service libraries, this isn't a big deal (the libs will automatically use a POST request instead of GET request if the request URL is too long).
Using the Data Element in Custom Code Boxes
You can use _satellite.getVar('hier1') to return the data element. Note that this returns an array, e.g. ['foo','bar'], so you need to use .join() to concatenate to a single delimited string value.
Using a different Delimiter
If your implementation uses a delimiter other than a comma (,) and you use the same alternate delimiter for all your variables, you can update the Data Element as such:
return location.pathname.split('/').filter(Boolean).slice(0,4).join('[d]');
Where [d] is replaced by your delimiter. Note that this will now cause the Data Element to return a single concatenated String value instead of an Array. Using %hier1% syntax in DTM fields remains the same, but you will no longer need to use .join() in Custom Code boxes.
If your implementation uses different delimiters for different variables, implement the Data Element per the original instructions in the first section. You may use %hier1% syntax in DTM fields only if the delimiter is a comma. For all other delimiters, you will need to populate the variable in a custom code box and use a .join('[d]').
Capturing more than Four Directory Levels
Since you are no longer trying to put a value in four hierarchy fields, you may consider pushing more levels to hier1 or other variables.
In the Data Element, change the 4 in .slice(0,4); to whatever max level of dirs you want to capture. Or, if you want to capture all dir levels, remove .slice(0,4) completely.
I am writing a program that takes advantage of IBM Watson's Document Conversion service to convert documents of various types into answer units. Each answer unit that is returned by the service contains an array named content which is composed of objects having a media_type and a text element.
I've never seen more than one element in this content array, and I'm not sure how to handle them if there were. Can there ever be more than one element in this array and, if so, what are the possible values? Will they all have the same media_type value? My plan at the moment is to combine all of the text elements into one if more than one exists.
The answer unit content array can have more than one element (if you request that - see below). If it does, each element in the array will be a different media type representation of the same contents.
You can get this by putting more than one output media type in your request. When you do this, the output content array will contain more than element - with an element for each of the media types you request.
For example, if your request contained a config like this:
{
conversion_target : 'answer_units',
answer_units : {
output_media_types : ['text/plain', 'text/html']
}
}
(see https://www.ibm.com/watson/developercloud/document-conversion/api/v1/#convert-document for explanation of where you put config)
Then the content in your response will contain:
content : [
{
text : <the plain text contents of the answer unit>,
...
},
{
text : <the HTML contents of the answer unit>,
...
}
]
If you don't specify the output media type parameter, you'll get the default value which is:
output_media_types : ['text/plain']
This is why you're always getting an array of length 1, with a text version of the output. Because implicitly, by leaving it with the default config, you're asking for one output media type.
The Answer Units converter currently only splits by heading tags (<h1> and <h2> by default). If you want to split your answer units more granularly, you can change the level at which it splits by passing in a custom configuration:
{
"answer_units": {
"selector_tags": ["h1","h2","h3","h4","h5","h6"]
}
}
See https://www.ibm.com/watson/developercloud/doc/document-conversion/customizing.shtml#htmlau
How can I get the complete selected text from an AutoComplete TextField?
If I use getText(), I only get the few letters the user has input so far.
Example: I write "flo" and then select "Flowers" from the list, but getText() gives me "flo"
AutoCompleteTextField auto = new AutoCompleteTextField(arrayWithNames);
auto.setMinimumLength(4);
auto.addListListener((ActionEvent evt1) -> {
String lookedFor = auto.getText();
Hashtable<String,Object> match[] = findMatch(lookedFor);
if(hMatch.length>0){
contElements.removeAll();
for (Hashtable<String, Object> Match1 : match) {
...
...//fill the Container with the names found
...
}
}
});
How it works
I am using the AutoComplete TF as a search button.
I have an array with all the names in my list.
Then I populate the Auto with the array.
The user selects a name from the Auto and then I search the value that is being "lookedFor" using the findMatch(). It returns a new array with the found entries.
I need the complete name from the list so I can use the findMatch() method, but when I use getText() from the Auto, it only returns the letters the user entered, and not the whole name, so my method does not work, since I am comparing whole Strings.
(I am using the Auto because it is very convenient if people remember only a part of the name they are looking for)
If you subclass AutoCompleteTextField you can access the selected text internally via getSuggestionModel().getItemAt(getSuggestionModel().getSelectedIndex()). Now you can define a public getter method getSelectedText() or something on your derived class.
I am not sure you are using the AutoCompleteTextBox correctly.
The entire purpose of the AutoCompleteText box is to help you assist the user in selecting from a list of valid requests,
You should not be getting the value of getText() until the user is ready to submit the form where the AutoCompleteTB is located.
This WILL help if you haven't already looked here:
https://www.codenameone.com/javadoc/com/codename1/ui/AutoCompleteTextField.html#getPropertyTypes--
Good luck!
There is a Doxygen option to specify when API appeared using \since tag, for example
///
/// Does foo
///
/// \since 1.5
///
void foo();
And it would appear in foo()'s documentation.
What I'm looking is a way to create automatically page that contains all API
appeared in 1.5 - i.e. list all API marked by \since 1.5 or probably
some other tag if available.
Edit: I tried to use \ingroup and create a group page containing all new API there and it works. But it moves description to this page, for example moves a new method from class definition to a page "New in 1.2.3" which isn't what I wanted.
You want to create an external reference to the current item, an \xrefitem:
\xrefitem version_change_1_0_0 "Since 1.0.0" "Changes in 1.0.0" ...
<key> <heading> <list title> <text>
All items that share the same <key> will be shown on a special generated page. The <heading> will be used to start a section at the place you're using \xrefitem, whereas <list title> will be used as a title for the resulting page (see remarks below). The text can be arbitrary.
The result you get is similar to the lists and appearances of\todo and \bug, and you can even think of \bug and \todo implemented as
\bug <text> = \xrefitem bug "Bug" "List of bugs" <text>
\todo <text> = \xrefitem todo "Todo" "List of todos" <text>
Unfortunately, the key cannot contain dots:
ID "$"?[a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF]*
LABELID [a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF\-]*
Therefore, you have to use an alias that takes (at least) two arguments, one for the label, and one for the actual text:
ALIASES += sinceversion{3}="\xrefitem version_changes\1 \"Since \2\" \"Changes in \2\" \3\n\n"
ALIASES += sinceversion{2}="\sinceversion{\1,\2,Introduced in this version.}"
If you never use dots, you can of course simplify the alias even more. This will give you two new commands:
\sinceversion{label, version}
\sinceversion{label, version, custom text}
In both cases, the label must only contain alphanumeric symbols, the version can be arbitrary. If you don't provide the custom text, "Introduced in this version" will be shown.
If there's a page with the identifier version_changes<label>, the list of changes will be added. Note that the \page's title will overwrite the title given by the \xrefitem, which can be handy for major releases.
Example
Here's an example of \sinceversion's usage. Note that you probably want to use another alias like ALIASES += since_vXYZ{1}="\sinceversion{X_Y_Z,X.Y.Z,\1}" if you document a lot of changes for version x.y.z:
Example code
/** Foos around.
* \sinceversion{001,0.0.1}
*/
void foo(){}
/** Bars around.
* \sinceversion{001,0.0.1}
* \sinceversion{002,0.0.2,Removed a memory leak}
*/
void bar(){}
/** \page version_changes002 Changes in 0.0.2
*
* We found several memory leaks and removed them
*/
List of version change pages
List of changes per version
List of changes per version with additional description
Appearance of changes in function documentation
It is well known how to obtain a TODO list in Doxygen, typing:
\todo Item one
\todo Item two
and so on, but when something has been done, how to keep track of this?
If I have done item two I don't want to remove it, I want to mark it as done:
\todo Item ono
\done Item two
How do I do this?
I dug around in the Doxygen documentation and stumbled over the \xrefitem. It's supposed to be:
A generalization of commands such as \todo and \bug. It can be used to
create user-defined text sections which are automatically
cross-referenced between the place of occurrence and a related page,
which will be generated. On the related page all sections of the same
type will be collected.
The first argument is an identifier uniquely representing the
type of the section. The second argument is a quoted string
representing the heading of the section under which text passed as the
fourth argument is put. The third argument (list title) is used as the
title for the related page containing all items with the same key. The
keys "todo", "test", "bug" and "deprecated" are predefined.
So you could specify a new alias, e.g. "done" in your Doxyfile:
ALIASES += "done=\xrefitem done \"Implemented TODOs\" \"Implemented
TODOs\" "
And in your code you should be able to use the new "done" tag like all the others:
/// \done fixed broken function
According to the doxygen manual there is no such "inverse" of the \todo command. Perhaps you can just keep the \todo and mark it manually as done, somehow.
Unfortunately doxygen's Markdown doesn't seem to support strikethrough (unlike Stack Overflow's, obviously), that would otherwise have been a good and common choice. Perhaps you can set it up using custom styling and spans.