There are a few minor issues with the tocs:

• Headings in tags that are collected for the module overview pages (e.h. @knownissue) create strange tocs - see https://docs.angularjs.org/api/ng "Double Compilation". The heading shouldn't be included at all in the collection of known issues. Solution: a) remove the heading b) introduce a "title" parameter to the @knownIssue tag that is rendered without id / without heading in the module overview page

• Examples have inconsistent headings:

  • the @example tag is not used consistently - Some pages include "Example" headings. Some pages use only the <example> element which is rendered as a usable example
  • the @example tag creates a simple heading "Examples" . This looks weird when there's only one example, and requires to manually set a heading when there's more than one example. The id is is based on the method name or in all other api contexts, simply "example"
  • Solution for @example :
    • could have "title" param that is extracted and set as an appropriate heading (based on the parent section?) -> since it's jsdoc, it should use the <caption>tag? see http://usejsdoc.org/tags-example.html
    • a single example in a section would be rendered just "Example" (+ caption if available)
    • a collection of Examples would generate a list of "Examples" with the titles / no entry when no "title"

• Sections / Headings with the same name generate incorrect links in the toc (e.g https://docs.angularjs.org/guide/accessibility). Solution: dgeni / markdown parser should generate unique heading ids OR if it works in the guide, use the @example tag -> doesn't work because @example is a jsdoc tag