Comments (10)
hi.. the example content is deliberately not escaped as some users like to embed real markup in their @example (some people use the output on internal sites which permit markup).. e.g.
/**
Constructs some UI widget or other
@example
<div data-create-widget="UIWidget"></div>
*/
function UIWidget()
{
...
};
now, in their generated documentation, the UIWidget renders inline as desired..
if you want to wrap your example in a code block use the standard markdown syntax of either
/**Perform foo
@example
foo('<a href="#baz">hi!</a>');
*/
function foo(bar)
{
return '<strong>' + bar + '</strong>';
};
or
/**Perform foo
@example
`foo('<a href="#baz">hi!</a>');`
*/
function foo(bar)
{
return '<strong>' + bar + '</strong>';
};
i'm working on the next version of the tool which has options to automatically wrap examples in code blocks, amongst other things
from jsdoc-to-markdown.
Ah, that is what I suspected. However the regular jsdoc (html output) has the opposite behaviour so an option would be indeed be useful. (I want to use both jsdoc and jsdoc2md in the same project)
Thanks
from jsdoc-to-markdown.
the jsdoc html output might look correct, but if you run jsdoc -X
against your code you'll see the issue in the underlying data.. try it:
$ jsdoc -X my-code.js
from jsdoc-to-markdown.
Yes I understand, this is why jsdoc does this escaping in the templates:
This was added because of jsdoc/jsdoc#511
from jsdoc-to-markdown.
hey there, i am testing the next version of the tool against your project - this is how the output currently looks: https://github.com/75lb/domv/blob/master/api.md
any feedback is welcome ;)
from jsdoc-to-markdown.
Awesome, that looks much better.
Here's some things I have noticed:
- Perhaps inherited methods / attributes (@Augments) should be listed in their own sublist, just like that new "instance" sublist
- Some of the markdown headings need an extra new line before or after them, see here https://github.com/75lb/domv/blob/master/api.md#external_Node
- Externals are not linked
@returns {?(module:domv/lib/Component|module:domv/lib/Component[])}
is shown asReturns: Component | Array.<module:domv/lib/Component--Component>
I am not sure what that--
is. See here https://github.com/75lb/domv/blob/master/api.md#module_domv.wrap
from jsdoc-to-markdown.
- good idea ๐
- ah yes, thanks
- yes, i will tackle this
- true - that needs fixing
thanks! will get back to you..
from jsdoc-to-markdown.
here are the domv docs generated using the latest jsdoc2md code, how does it look?: https://github.com/75lb/domv/blob/master/api.md
- implemented.. take a look at
domv/lib/HtmlDocument
.. if you click an inherited member in the class member index it takes you to the docs in the parent class (Component).. this reduces duplication in the docs (before, docs for inherited Component members were duplicated inside the docs for HtmlDocument).. - this was caused by
<p>
tags in the domv jsdoc documentation that did not have a closing</p>
.. - done
- done
from jsdoc-to-markdown.
awesome that looks much better! I do not see any other issues, thanks
I committed the missing </p>
from jsdoc-to-markdown.
good, glad you like it.. i will package up a pre-release of jsdoc2md for you to experiment with.. will get back to you later..
from jsdoc-to-markdown.
Related Issues (20)
- How to recursively document every .(m|c)js(x) files of a project? HOT 1
- How to describe interface with properties? HOT 2
- Decorated classes get named "_class" in output .md file HOT 2
- Support for TypeScript types inside JsDoc? HOT 4
- This experimental syntax requires enabling the parser plugin: "importAssertions" HOT 10
- How to group ES2015 modules? HOT 2
- Option to specify which jsdoc binary should be used HOT 5
- Is there any fix for the TYPESCRIPT Comments that aren't shown?
- command-line option "template" requires a value. HOT 3
- can't parse typescript file content with Node.js api getTemplateData HOT 1
- Missing documentation for classes with constructors HOT 1
- The "โ" character becomes "รรงร"
- Ignoring instance method parent name? HOT 1
- [feature request] Support optional instantiate parent name prefix
- can system helpers be overridden?
- FEAT: Include filename for each function in Markdown
- Doc not generate and no error message HOT 1
- Security Issue and Deprecation Warning in jsdoc-parse due to lodash.pick HOT 2
- Required and optional parameters are not distinguished.
- markdown-it < 13.0.2 security vulnerability
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from jsdoc-to-markdown.