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
Related
I need some guidance on how to add a drop down list from an array of data after the read info from the MP4 Tag data is parsed. The mechanism I'm using is 100% operational, this is a creature feature addition. The MP4 tag I'm working with is Genre using the ID3V1 standard. There are 191 choices. The way my app was inherited, there are 2 columns, property/value and multiple rows. All of that works. The Genre tag was setup willy nilly so you could basically type whatever and it would store it. I want to remove that and have the 191 elements in the array to choose from using the drop down list. Part of the loading process is that it will pull in whatever was in the MP4 file. So, I want the user to be able to leave as is (most likely tagged by something that supports ID3V2), or select from the populated 191 elements in the dropdown list.
The object looks like this information.h:
protected:
CMFCPropertyGridCtrl m_wndProperties;
The information.cpp looks like this:
void CInformationView::OnInitialUpdate()
{
// create property grid
VERIFY(m_wndProperties.Create(WS_CHILD|WS_VISIBLE|WS_TABSTOP| WS_BORDER, CRect(0,0,0,0), this, 0));
// get document
CMovieDoc *lpkDoc = GetDocument();
ASSERT_VALID_PTR(lpkDoc);
// add properties //Information ORDER Loading <<<<< List shortened Stack overflow question
m_wndProperties.AddProperty(lpkDoc->m_pkArtist);
m_wndProperties.AddProperty(lpkDoc->m_pkTempo);
m_wndProperties.AddProperty(lpkDoc->m_pkGenre);
CView::OnInitialUpdate();
}
The way it pulls the data in from mp4.cpp:
// Genre
m_pkGenre = new CMFCPropertyGridProperty(_T("Genre"),
COleVariant(AfxStringFromUtf8(lptTags->genre), VT_BSTR));
The pointers in mp4.h:
CMFCPropertyGridProperty *m_pkArtist;
CMFCPropertyGridProperty *m_pkTempo;
CMFCPropertyGridProperty *m_pkGenre;
Now I know that pull downs in the 2nd column (Values) can be done because other tags have simple TRUE/FALSE that can be selected, so that tells me it should be possible to create the drop down list I'm looking to do. An example of the TRUE/FALSE looks like this:
// Compilation
m_pkCompilation = new CMFCPropertyGridProperty(_T("Compilation"),
COleVariant((!VALID_PTR(lptTags->compilation)) ? (short)0 : (short)*lptTags->compilation, VT_BOOL));
I've done arrays in C for things like microcontrollers, but not entirely sure if it is the same in C++. I'm thinking it should look like this:
// Initialize Genre Array
const char *genre[4] = { "Rock", "Rap", "Soul", "House" };
The questions are:
How do I create an the array (or does my example above look correct?) to house fixed strings like "Rock", "Rap", "Soul", etc. etc?
How to modify the VALUE row to have the pull down that contains the parsed Genre tag present and then when opened, show the 191 Genre tags where one can be selected to choose from (and ultimately save which is already working).
Actual code, not references to the learn.microsoft.com, the few things I've tried crashes when I try to alter the AddProperties I assume because of the lpkDoc pointers being used.
You should not use a plain old C-style array if you do not have a strong reason to. Use a std::vector instead. You don't even need to indicate the [size].
The same goes for char *. Use a CString or astd::string instead.
const std::vector<CString> = { L"Rock", L"Rap", L"Soul", L"House" };
Don't make your life harder than it needs to be.
2.
for (size_t i= 0; i < genre.size(); i++)
{
auto gnr= genre[i];
lpkDoc->m_pkGenre->AddOption(gnr);
}
or even better
for (auto it : genre)
{
lpkDoc->m_pkGenre->AddOption(it);
}
Important note: You should not have code about properties in your doc object. You are mixing business logic with user interaction logic. Your code in the future will be a nightmare to maintain.
I do not see your lpkDoc->m_pk variable init'ed anywhere, and I bet those pointers are pointing to no man's land.
I need your help.
Now I am using AsciiDoc and AsciiDoctor to create some manuals.
I want texts smaller on some specific blocks, for example wide table, wide list, and so on, but not want main texts smaller.
Especially I need to make texts of wide tables smaller as my customer requests so.
Is there any way?
You mention lists and tables...
About lists, it can't be done as stated in AsciiDoctor Documentation:
Unsupported
Complex AsciiDoc markup is not permitted in attribute values, such as:
lists
multiple paragraphs
other whitespace-dependent markup types
As you can see, there it mentions multiple paragraphs, so while #EhmKah answer is a correct way to set a custom styling block, it won't be rendered as expected in a table/list as it's multi-paragraph.
The Built-in CSS class syntax is the way to go [small]#any phrases#
But in order to make this work in a table, you must set the cell type with a specifier in this case, the AsciiDoc specifier denoted by a
This means the cell (or column) will render supported AsciiDoc statements, attributes, etc.
Here's a working example:
[frame="none",grid="none"]
|====
a| image::images\logo.png[] a|[.small]#Autor: {author}#
|====
If you have tons of rows/columns, you don't have to manually apply the a to all of them. You can set the columns you need this behavior this way:
[cols="1a,2a",frame="none",grid="none"]
|====
| image::images\logo.png[] |[.small]#Autor: {author}#
|====
You can check its documentation for more about Column Formatting and you can check the Rendered table with variable widths and alignments sub section for more about AsciiDoc (a) and other specifiers.
docinfo.html + --attribute docinfo=shared
You can drop your CSS modifications into a file called docinfo.html:
<style>
/* Your custom CSS. */
</style>
and then build with:
asciidoctor --attribute docinfo=shared README.adoc
and that makes Asciidoctor 2.0.10 place docinfo.html at the bottom of the <head> element.
So you can override most of the default Asciidoctor style from there.
Then it's just a matter of understanding the generated HTML and previous style definitions to override them.
For image specifically, see also: How to set a custom image height for an image in Asciidoctor?
When you use a theme file, you can add a role to it like this:
role:
mycustomfont:
font-color: #333
font-size: 10
Now you can reference your newly created role right from your table cell:
a|[.mycustomfont]# some text #
I read something about
[small] and [%autofit] option https://github.com/asciidoctor/asciidoctor-pdf/issues/185 I never needed it so maybe you give it a try.
example-code
[small]
----
should be rendered in smaller font.
----
[%autofit]
----
really long text that doesn't want to fit on a single line with the default font size, so we'll make it shrink to fit.
----
I am about to build a block for creating content tables in Episerver.
I would like this block to have a ContentArea which in turn will contain only blocks of type TableRowBlock (so that I can have an arbitrary number of rows).
If I create a block type called TableBlock and another one called TableRowBlock, they will both be visible when an editor adds a new block.
Since TableRowBlock only makes sense within a TableBlock, I would like to hide it so that it is only visible when adding a block to the ContentArea property of a TableBlock.
How can I do this?
What you're asking isn't supported out-of-the-box, I'm afraid.
However, you could:
Add an [AllowedContentTypes] attribute to your ContentArea property for TableBlock, and specify the TableRowBlock type as the allowed type. That way the editor won't have to select block type when clicking "Add new block" in the content area editor.
Customize which content type(s) are suggested when new content is created by creating your own IContentTypeAdvisor which would suggest TableRowBlock when TableBlock is being edited:
[ServiceConfiguration(typeof(IContentTypeAdvisor))]
public class ContentTypeAdvisor : IContentTypeAdvisor
{
public IEnumerable<int> GetSuggestions(IContent parent, bool contentFolder, IEnumerable<string> requestedTypes)
{
// Suggest relevant content types
}
}
Full example available here.
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.
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.