I'm having a strange issue with the #todo command when I have other formatted data below it in a list in the latest version of doxygen (1.8). Consider the following example:
/**
#page build_instructions Build Instructions
- Library1
- #todo Detail build process
- get source
- build release/debug version for x64
- build release/debug version for x86
*/
If you run it, you will notice that the #todo tag adds extra indentation to the last two list items (after "get source"). If you remove the #todo tag, then the indentation looks OK. Also, if I remove the - in front of #todo, it encloses the items below it in a box.
Is this a bug? How can I make the #todo tag affect only one line?
I can confirm this: your code works in 1.5 but not 1.8, so it seems like a bug. Two possible workarounds follow:
try putting the todo item as the last element in the list,
if you want the todo item at the top (or anywhere other than the last element) in the list, then try putting a blank line in between each of the list items which follow the todo item.
Related
I'm using Docusaurus to publish documentation for an open source library's API. The headings of my source markdown files correspond to the names of methods and properties for classes in the library. This all works fine.
However, the anchors that are created in the HTML are all lowercase. I want them to respect the capitalization used in the markdown file.
For example, this markdown header:
###.doSomething()
Generates the following HTML:
<h3>
<a aria-hidden="true" tabindex="-1" class="..." id="dosomething"></a>.
<code>.doSomething()</code>
<a class="..." href="#dosomething" title="...">#</a>
</h3>
As you can see, camelCase is transformed to lowercase. I would like to keep capitalization intact. Is it possible?
P.S. The markdown files are automatically generated from jsdoc comments. In jsdoc, links to a method or properties include capitalization.
TL;DR
Inside your project, navigate to the directory node_modules > github-slugger;
Open the index.js file;
Remove the line if (!maintainCase) string = string.toLowerCase()
The function will become something like this:
function slugger (string, maintainCase) {
if (typeof string !== 'string') return ''
// if (!maintainCase) string = string.toLowerCase() <-- remove this!
return string.trim()
.replace(specials, '')
.replace(emoji(), '')
.replace(whitespace, '-')
}
IMPORTANT!
If you update the docusaurus, you may need to apply this change again;
It may be necessary to edit the doc to see the changes, because of cache. Here I edited the doc file and it worked;
You must restart the docusaurus service after you make this change. And probably needs to clear the cache with npm cache clear --force;
Also, I think you should delete the folder .docusaurus to force the rebuild of all documents.
RESULT
The .md file:
---
id: intro
---
# Random title
### WriNTinG with CaSeS
test 1
### .doAnotherThink()
test 3
### .doCamelCaseWithSeveralLETTERS()
test 3
ROADMAP
I must say that this one was hard. First I tried to track down the anchor tags, then the description. Eventually I found about the github-slugger, and looked like that was the way.
But once I made the changes, nothing had happened to the document! So after hours trying, I gave up… Then, just for curiosity, I decide to see what the slug function did to the document, by adding a second header with the same name. And — luck! — it kept the original case.
It turns out that you can simply use explicit IDs to solve this issue: https://docusaurus.io/docs/next/markdown-features/headings#explicit-ids
I faced with the problem of writing my vcs current branch name each time I have written 'todo' comment.
Recently I learned about Intellij's 'Live Templates' which is quite comfortable to use. I tried to apply it to my problem but there's no templates to take out a branch name.
So the question is could I actually take out the name of my branch to code comments somehow?
It is possible to use the groovyScript predefined function and a script to extract the branch name. For example create the following live template:
$COMMENT$ todo [$BRANCH$]: $END$
with abbreviation "todo" and description "Inserts todo comment with branch name". Click Edit variables and give the variables the following definitions:
COMMENT:
lineCommentStart()
BRANCH (updated for 2020.2 and newer)
groovyScript("com.intellij.dvcs.repo.VcsRepositoryManager.getInstance(_editor.project).getRepositoryForFileQuick(com.intellij.openapi.fileEditor.FileDocumentManager.getInstance().getFile(_editor.document)).getCurrentBranchName()")
Skip if defined checked for both variables. The Groovy script is (unfortunately) all one line. Set applicable contexts to Everywhere.
With this live template it is now possible to type todoTab somewhere in a source file and a line comment with the branch name will be inserted. This will insert the proper line comment depending on the language of the file, or nothing in case of languages without a line comment like HTML. And should extract the branch name no matter the type of version control used (I tested with Git).
For live templates you can use predefined functions. Unfortunately there is no function to detect the current VCS branch.
But you can create a template to make work a little easier:
// TODO [$branch_name$]: $comment$
With this template, you still have to fill branch name, but you should not type symbols like [ and caret will be placed automatically.
You can also create a feature request for a new predefined function.
When queuing a new build I want to specify a label, as says in the Tooltip (see image below) like:
LMain_TestProject_1.01.002
However, that does not work, I have to put it with this format:
LMain_TestProject_1.01.002#$/TestProject
What I have to do to only specify the source version as: LMain_TestProject_1.01.002 ??
Thanks!
This is usually because the label you created is project-scoped, not collection-scoped. In this scenario, you need to add "#/ProjectName".
Usually, when you create a label from VS, you should see the seting like following:
With this setting, the label is project-scoped. You need to enter "LTestLable#/EddieLabel" when queue build.
More information for your reference: Label scope revealed.
Is there a way to modify the template IntelliJ uses for a method's Javadoc?
In particular, I want my javadoc comments to look like this:
/********************
*
* Comment here
*
*********************/
However, when I reformat the code, the javadoc ends up looking like this:
/**
* ******************
*
* Comment here
*
********************
*/
It doesn't seem like you want JavaDoc comments then, as they are defined to look like how IntelliJ is making them.
Format of a Doc Comment
Structure of a JavaDoc comment
You can disable JavaDoc formatting:
Settings > Project Settings > Code Style > JavaDoc
Uncheck Enable JavaDoc formatting
This way, you can have your multi-line comments not get reformatted as JavaDoc comments.
IntelliJ is identifying them (correctly) as JavaDoc comments since they have two asterisks.
You can also change them to regular multi-line comments (not JavaDoc comments) by adding a space before the second asterisk (e.g. /* ****************), which should also have IntelliJ not reformat them.
I am creating internal documentation for a C++ project using Doxygen. I am having Doxygen include the source for methods, etc., but this makes the page kind of hard to scan. I'd like it to behave like rdoc and hide the source in a block that is collapsed by default.
I thought that HTML_DYNAMIC_SECTIONS might let me do this, but alas, the changelog says that option only affects diagrams and graphs.
Maybe I could do it by editing the LAYOUT_FILE?
Anyhow, smart people, how can I coerce Doxygen to generate collapsable code sections?
if includ[ing] the source for methods, etc, [...] makes the page kind of hard to scan, why don't you just link to it (SOURCE_BROWSER = YES) instead of including it (INLINE_SOURCES = YES)? this would make the pages easier to scan and faster to load, and the source would still be accessible (at the expense of one more source page load). depends on how often you actually need to access the source, i guess.
that being said, there is a way to generate collapsible code sections (you will have to modify the source and recompile Doxygen, though):
collapsible sections in Doxygen's HTML output are marked with two nested <div>s like so:
<div class="dynheader"><div class="dynsection">
[collapsible section]
</div></div>
included code sections are marked like so: <div class="fragment"><pre class="fragment">...</pre></div>
thus, to make the included code sections collapsible, you have to either
modify the code that generates the <div class="fragment"><pre class="fragment">...</pre></div> to generate <div class="dynheader"><div class="dynsection">...</div></div> (and probably adjust some css), or
change the javascript initDynSections() function that scans and collapses the collapsible sections to recognize <div class="fragment"><pre class="fragment"> as one of them.
the implementation (or going the SOURCE_BROWSER route :)) is left as an exercise for the reader. good luck!
oh, and if you should succeed with a patch, it would be great if you could submit it to dimitri so that he can include it in a future version. thanks!
coming along here using the search engine of my choice i just want to leave a note here that it is not absolutely necessary to modify any doxygen source.
When this question was asked there was probably no possibility to embed pure html using the htmlonly tag but with this in mind one is able to create foldable container sections abusing a function named toggleVisibility
function toggleVisibility(linkObj)
{
var base = $(linkObj).attr('id');
var summary = $('#'+base+'-summary');
var content = $('#'+base+'-content');
var trigger = $('#'+base+'-trigger');
var src=$(trigger).attr('src');
if (content.is(':visible')===true) {
content.hide();
summary.show();
$(linkObj).addClass('closed').removeClass('opened');
$(trigger).attr('src',src.substring(0,src.length-8)+'closed.png');
} else {
content.show();
summary.hide();
$(linkObj).removeClass('closed').addClass('opened');
$(trigger).attr('src',src.substring(0,src.length-10)+'open.png');
}
return false;
}
that is currently available every time the documentation is generated in a file called dynsections.js placed in the documentation root.
Regarding this code one gets to know the conditions to be able to create foldable code from his/her own documentation using Javascript avoiding inner execution faults in this function and preventing further javascript code from being uninterpreted.
dom element with a unique identifier id
another encapsulated dom element with unique identifier id-summary
another encapsulated dom element with unique identifier id-content
another encapsulated dom element with unique identifier id-trigger
the id-trigger element must contain a src attribute with at least 1 character
the class attributes of the main containers do not matter
With theese conditions in mind one can create the following code.
## Fold me
## <div id="example-div">
## <div id="example-div-summary"></div>
## <div id="example-div-content">
## <pre>
## foo
## bar
## </pre>
## </div>
## <div id="example-div-trigger" src="-"></div>
## </div>
## #htmlonly <script type="text/javascript">$("#example-div").ready(function() { toggleVisibility($("#example-div")); });</script> #endhtmlonly
The doxygen code above is used to document bash code using bash-doxygen so it might look a bit different from pure doxygen code. The first part involving the div containers is already described mentioning the conditions to fit the source of the function toggleVisibility and make it executable without any errors adjusting the doxygen comments for our needs.
The unique id prefix used in here is example-div. In line one there is a hyperref link setup to unfold a section using javascript directly in conjunction with some jQuery code.
What's left is the one liner at the end. It contains the jQuery script need to be run to initially fold the specific segment. For the bash-doxygen (and probably other languages) the block needs to be a one liner because of the script's block scope
Normally the contents between \htmlonly and \endhtmlonly is inserted as-is. When you want to insert a HTML fragment that has block scope like a table or list which should appear outside <p>..</p>, this can lead to invalid HTML. You can use \htmlonly[block] to make doxygen end the current paragraph and restart it after \endhtmlonly.
as noticed in the doxygen documentation and a comment below the right marked solution of the stackoverflow answer on including script tags in doxygen documentations.
Thank you for reading.
Hope this helps some people that come along here.