How do I set a JSDoc tutorial title? - jsdoc

I'm using JSDoc tutorials, as described in http://usejsdoc.org/about-tutorials.html
I can't get the configuration options to work, and I haven't yet found any examples or discussion of the topic online.
In my trivial example, I pass a tutorials parameter to JSDoc, and it builds a tutorial file for tutorial1.md. I would like to give this tutorial a display name of "First Tutorial".
Following this from the online docs:
Each tutorial file can have additional .js/.json file (with same name, just different extension) which will hold additional tutorial configuration. Two fields are supported:
title overrides display name for tutorial with the one specified in it's value (default title for tutorial is it's filename).
children which holds list of sub-tutorials identifiers.
I tried several attempts at adding tutorial1.json, or tutorial1.js but either JSDoc pukes on the json file, or doesn't seem to recognize anything I throw at it in the js file.
Can anyone suggest a simple format for a tutorial configuration file that should work?
(Edited to include one .js file I tried, which did not change the tutorial display name.)
tutorial1.md
First Tutorial
================
tutorial1.js
/**
#title First Tutorial
*/
#title = "First Tutorial";
title = "First Tutorial";

It works with .json extension but not with a .js extension. jsdoc does not seem to try to even read the file if a .js extension is used. So the doc seems incorrect.
With a .json extension, and using jsdoc 3.2.2, the following works:
{
"title": "Custom Title"
}
Your .json file needs to be in the same directory as your .md file and have the same name (ignoring extensions).

Related

exiftool write xmp tag

I am trying to write a new value for a XMP tag using exiftool but for some reason the tag is not being recognized.
Reading the field works:
exiftool -PropertyId /Users/user/test.jpg
Property Id : 17934
But when trying to write a value for PropertyId tag, does not work.I did try also to use -xmp:PropertyId but I get the same result:
exiftool -PropertyId=12345 /Users/user/test.jpg
Warning: Tag 'PropertyId' is not defined
Nothing to do.
Exporting the metadata shows that the field is there: (I only copied the xmp section)
exiftool -xmp -b -a /Users/user/test.jpg > data.xmp
...
<rdf:Description rdf:about=''
xmlns:xmp='http://ns.adobe.com/xap/1.0/'>
<xmp:Brand>Brand Name</xmp:Brand>
<xmp:CreateDate>2015-07-08T11:45:21</xmp:CreateDate>
<xmp:CreatorTool>CreatorTool</xmp:CreatorTool>
<xmp:FacilityName>The Restaurant Name</xmp:FacilityName>
<xmp:MetadataDate>2015-09-14T13:12:51-06:00</xmp:MetadataDate>
<xmp:ModifyDate>2015-09-14T13:12:51-06:00</xmp:ModifyDate>
<xmp:PropertyId>00000</xmp:PropertyId>
<xmp:PropertyName>Property Name</xmp:PropertyName>
<xmp:ShootDate>2016-03-12</xmp:ShootDate>
</rdf:Description>...
I am missing something? Test file is here: test.jpg
Exiftool cannot edit metadata it does not have a definition for, as it is in this case. In fact, your example XMP shows a lot of tags which it says are part of the "xap" group but are not actually part of that (very old) standard, including Brand, FacilityName, PropertyName, and ShootDate. You'll find that none of those are directly editable by exiftool. Probably not by any other program except the one that originally wrote it.
If you want exiftool to be able to write those tags, you'll need to create definitions for those tags. See the ExifTool Example Config file for details.
Also take note, as I said, "xap" is a very old standard and has long since been replaced. Exiftool will update the tags it does know to the newer standards. For details see the XMP xmp tags entry.

Setting BOT properties in AIML

In AIML I have seen various files where the Bot properties is being used. For example :
<bot name="name" />
Here, the bot name is being used, but I am not able to find the place where to set this property, i.e. where should I define the name.
On searching I found that its stored in the .properties (link) file, but I cannot find the file anywhere.
There is also a github repsitory which has many files and used the bot properties, but here also no .properties file : Repo Link
So, where should I store the .properties file and if not then how should I add the bot properties in AIML.
As the AIML 2.0 working draft said:
The AIML standard does not specify where or how the properties, sets, maps,
substitutions and predicates are defined. This is an implementation detail
left up to the interpreter designer.
As an example, I am working with program-ab which is a Java implementation of the AIML interpreter.
The properties info of a bot is placed in a file named
config/properties.txt.
The format is like:
name: Alice
age: 22
gender: female
You can find more info about the program-ab configurations at Configuration.wiki.
If you are working with other kinds of implementation such as Python or whatever, the properties file path and its format may be found inside the wiki or docs.

Doxygen : Section id only alphanumerical since 1.8.15-git

I am working on this project : https://sbl.inria.fr/doc, where the documentation is done with doxygen.
We were used to define the id of our sections with the symbol "-" to separate the words, for example :
\section sec-intro Introduction
However, it looks like the convention has changed since doxygen 1.8.15-git and only alpha-numerical characters are accepted, breaking almost all the pages in our documentation.
Unfortunately, we have a large number of pages, and before reviewing the whole documentation, I wanted to know if there is anything that I am missing, like a doxygen option to turn ON / OFF
[edit]
Here is a minimal example that does not work for me, with doxygen 1.8.15-git:
/**
\mainpage My Main Page
Abstract
\section home-intro Introduction
Intro
*/
//! Documented class test
class test{
};
I just create the configuration file and then run doxygen on the directory containing my .hpp file (so that there is no need to specify the path to my header) :
doxygen -g; doxygen
The main page on the output html contains "Abstract", but not the section, and there is a warning in the doxygen log :
test.hpp:6: warning: Invalid section id `home'; ignoring section
[edit 2]
It worked with doxygen 1.8.14. I cloned the project from the git repository, so I had the latest version. Using the tag version for the 1.8.14, it works fine. I changed the title.
I found the cause of the problem, it is a regression on:
Bug 740046 - Negative sign in -Foo::Bar ruins hyperlink in generated output
The github issue causing the problem is https://github.com/doxygen/doxygen/pull/5677 and the pull request https://github.com/doxygen/doxygen/pull/704.
The issue has been fixed in the proposed patch: https://github.com/doxygen/doxygen/pull/6388

Is there a detailed documentation on how to create own jsdoc templates?

Short version:
If I wanted to develop a completely new jsDoc template from scratch, what would I have to read to understand what jsDoc does, what interface my template must provide and what data I get to work with?
Long version:
I've been using jsDoc for a while now and have come across some tags that I would like to add and overview pages that I would like to have generated out of my documentation. Up to now I solved all my "user problems" with usejsdoc.org. I even managed to add a new jsdoc plugin that adds some tags. However, I can't find any developer documentation on how to create templates for jsdoc. I use ink-docstrap so I clicked my way through the template-folder (publish.js, /tmpl, etc.) and somehow got the idea of how everything works. But its very very time consuming.
What should I read to become a jsDoc template pro?
These instructions are the closest I could find:
To create or use your own template:
Create a folder with the same name as your template (for example, mycooltemplate).
Within the template folder, create a file named publish.js. This file must be a CommonJS module that exports a method named publish.
For example:
/** #module publish */
/**
* Generate documentation output.
*
* #param {TAFFY} data - A TaffyDB collection representing
* all the symbols documented in your code.
* #param {object} opts - An object with options information.
*/
exports.publish = function(data, opts) {
// do stuff here to generate your output files
};
To invoke JSDoc 3 with your own template, use the -t command line option, and specify the path to your template folder:
./jsdoc mycode.js -t /path/to/mycooltemplate
Failing that, you can read the source code!
I am running into a similar difficulty with lack of documentation. There is a GitHub issue that has been open for 7 years on this: Provide docs that explain how templates work.
The only example I've found so far of a custom template that doesn't look like just a modified version of the default is Ramda's documentation. It looks like they use a completely custom publish.js script that uses handlebars.js instead of underscore.js templates, constructs a non-hierarchical nav, pulls info from #sig and #category tags, and uses links to github for 'view source' instead of rendering its own html pages for source code.
Some of their code will be difficult to understand unless you are familiar with Ramda and functional programming (they use Ramda itself in their version of publish.js) but dumping out the values of data and docs during execution should help provide insight into what is going on.
It is helpful as well that their template is a single file so you don't have to jump between a lot of partial template files to follow how the doc is constructed.
I've just published my own new jsdoc theme. What I did is I simply copied the default template: https://github.com/jsdoc3/jsdoc/tree/master/templates/default, and worked on that.
I also managed to add grunt with the following features:
* transcompile + minify js files
* parse sass styles and minify them
* refresh the docs when you change something
You can see how it works here: https://github.com/SoftwareBrothers/better-docs
you can customize one of existing templates (default, haruki or silent):
go into node_modules/jsdoc/template and grab on of them into your app directory outside node_modules.
feel free to rename the dir ex: jsdoc-template.
open jsdoc-template update/customize the content as you want. ex: open publish.js find Home and replace My Js App.
update jsdoc.json by adding:
"opts": {
"template": "jsdoc-template"
}
another option to use one of those templates too: jsdoc3 template list examples
Followup to my previous comment about Ramda's JSDoc template. I've since created a customized version of it and published it on GitHub at https://github.com/eluv-io/elv-ramdoc
This is tailored for my company's projects, but it may be helpful as another learning tool. It adds a 'Show private' checkbox, updates Bootstrap to v5.13, replaces Handlebars with Pug, adds JSDoc comments to the publish.js script itself, and supports setting an environment variable to dump data to console during doc generation.

jsdoc tags within html files

after building a web app, I tried out the jsdoc-toolkit. In a config file I added my index.html to the list of source files and also used the x-parameter to make the toolkit aware of the html file.
java -jar jsrun.jar app\run.js -t=templates\jsdoc -x=html,js -c=conf\my.conf
While the doc is generated without any errors, it still ignores any jsdoc annotation I made within the index file.
And when I check the generated doc, the index.html file is listed as source file.
Very simple documentations such as
/**
* testing the doc
* #constructor
*/
function Test(){
}
are simply ignored
Probably because its embedded in tags.
Do you have any idea how to force jsdoc to use this code as well?
Cheers,
zbug