I have documented my code with doxygen. The generated docs consist of:
a page with the documentation as I put between /** ... */, and
a page with the source-code itself (without the documentation between /** ... */).
Now my question is: Is there a way to generate links such that one can reach the page with the source code opened on the relevant line directly from the documentation?
To show visually what I would like to obtain:
I would like to have a button "Go to source" (shown in red, decorated with an arrow just for here).
Which would land me on the right line of the source code (possibly with a highlight, as shown here).
The following option does exactly that:
SOURCE_BROWSER = YES
Thanks #albert!
Related
I am writing API doc comments and would like to include code examples in a comment block with comments included in this same block. I have change the font color for the block comments themselves but not for the comments in the comment.
Is there a way to edit the colors/text-decorations of these? I find it too dark and difficult to read. This happens with every theme I have installed.
This is not related to VS Code, you can highlight an example of the code usage using JSDoc tags. In your instance you're looking for #example:
/**
* #example
* myFunc('calling my func');
*/
function myFunc(args) {
}
And you will see your code sample highlighted in VS Code:
Does anyone know how to create a link to the header of a different wiki page?
I know if I have a header ##Header name that I can link to it on that page by using (#header-name) as my link, but I want to link to that header from a different page. Is this possible?
ie. I want to have a table of contents that can link to the sub-sections of each wiki page as well as to the page itself.
Edit: I mean a way besides just using the url link
http://github.com/project/wiki/Wiki-Page#header-name
EDIT 1: So totally wrong about before, I just read up a bit more. So we have this new support as well inside of GitHub Wikis! (Relatively new.)
You can also do something like this:
[[ Link text | page_title#header_title ]]
This might work a lot better for you! TIL because of this answer here. You can see me do this with the Prerequisite link and you can see my other links work the other way. Time for me to do some updates!
EDIT 1: Still useful but definitely NOT THE ONLY WAY.
So I answered a question about this before, you should avoid absolute links on GitHub (i.e. https://github.com/user/repo_name/...)
However, a good way (and kind of the only way inside of Wikis EDIT 1: TOTALLY NOT TRUE TO BEING THE ONLY WAY) of doing what you need can be seen like this:
[Header link](/user/repository_name/wiki/page_name#title).
This is kind of the linking unfortunately that the Wiki would support. This will change your directory page based off of GitHub. You can see that it would be
https://github.com/(the linkage you want to hit)
I have actually began doing something like this in a Wiki I work on here. Inside of my Sidebar, you can see I have a Getting Started Page, and then a subsection into it is a Prerequisite heading and it will properly lead people to where they need to go. You would be able to perform this same thing on any page. It is a tad verbose, but worth it as you can easily change things around if need be. This is also case-sensitive since it will change their location so be sure that in your linkage, the page is the proper case and your heading is all lowercase.
Hope this helps!
You can link to the header by simply assigning an id to header. e.g you've "Extension" header in a page called Abc.
# <a id="extension"></a> Extensions
You have another page "Call center" and you want to go to extension in abc , you can use reference linking of markdown i.e "The [extensions][1] are handled by agents"
[1]: url-of-abc/#extension
I tested Maxwell's "good way" to link to the header of another page in Github in Edit 1 on and it works perfectly.
#[crux-ports Installation](/user/crux-ports/blob/master/README.md#installation)
markdown generate slug for the heading and convert it to id, example
# [ topic ][ color ]
will be converted to
<h1 id="topic--color" data-line="643" class="code-line">[ topic ][ color ]</h1>
Thus, to link it you can write it as [color](#topic--color).
If the destination anchor is on another page (assume filename css.md) with path relative to current markdown page, then you can write it as [color](css.md#topic--color)
Attach the slugify function from vscode
// excerpt from https://github.com/yzhang-gh/vscode-markdown/blob/908d7ba5465a203e4299f346c179211d992ef468/src/util/slugify.ts
const str = '# [ topic ][ color ]';
const slug = encodeURI(
str.trim()
.replace(/\s+/g, "-") // Replace whitespace with -
.replace(/[\]\[\!\'\#\$\%\&\'\(\)\*\+\,\.\/\:\;\<\=\>\?\#\\\^\_\{\|\}\~\`。，、；：？！…—·ˉ¨‘’“”々～‖∶＂＇｀｜〃〔〕〈〉《》「」『』．〖〗【】（）［］｛｝]/g, "") // Remove known punctuators
.replace(/^\-+/, "") // Remove leading -
.replace(/\-+$/, "") // Remove trailing -
);
console.log(slug) // "topic--color"
I use some external libraries in my project, e.g. libev.
I realize I can use markdown (or href) and put
[libev](http://software.schmorp.de/pkg/libev.html)
in my document.
However that only works in a single place, and I don't want to have to put that in the dozens of places I refer to libev.
If it's "ClientWatcher" (one of my classes), doxygen auto links to the class.
Is there some way to tell doxygen to make all occurrences of the word "libev" auto link to http://software.schmorp.de/pkg/libev.html (for example)
If you add
ALIASES += libev="libev"
to Doxygen's configuration file you can use the \libev command to generate a link, like so
/** #mainpage
* See \libev for more info.
*/
I have added this to a class comment:
#link http://www.google.com Google #endlink
However, when I generate documentation using doxygen, the link text is indeed "Google", but the link is to:
file:///media/portable/Examples/Doxygen/link/html/classClass1.html
Can anyone explain what is going wrong?
I think you are using \link incorrectly. From the doxygen documentation, \link is used to refer to objects like a file, class or member and takes a reference to one of these as its first argument. For example, if I wanted to refer to a class method func in the class myClass, I would use
\link myClass::func link text ... \endlink
with all of the remaining arguments considered to be text for a link. I think your problem is that you do not pass a valid object as the first argument. I would guess that classClass1 is the next object in the file where you tried to include the link and this is what the \link command is refering to.
Linking to URLs
Doxygen will generate URL links automatically, so there is no need to surround the link with \link and \endlink or any other commands. So remove those and see if that fixes the problem.
To manually specify link text, use the HTML 'a' tag:
link text
For more information about how doxygen handles automatic linking see this documentation page.
Is is possible to show the source code being commented with Doxygen?
I have tried the following:
if (u[index] == ']') /**< Detailed description after the member */
and only got the following result:
< Detailed description after the member
Is there any way to force Doxygen to show the code snippet along with the comment?
If you want to show a code snippet and not from the source code itself, use #code, #endcode to enclose a code snippet within the class/method documentation.
No, but you can configure doxygen to include a source browser that contains the code, and put links from the generated documentation to the source code.