Issues with the table of contents in the doc app

[Narretz]

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

[5earle]

Good day. i am a student studying open source at Seneca college, and would like to take a go at this project.

[nik72619c]

Shall I work on this if no one else is ? Willing to work on this issue.

[petebacondarwin]

@nik72619c if you would like to submit a PR we will happily review it and merge it into the docs.

[nik72619c]

Sure ! working on this one. For the Double compilation heading, should I make changes to the known issue part of the $compile section?

[petebacondarwin]

Yes I think that is simplest.

[nik72619c]

So I think taking it out of the known issues section and making it a separate heading might solve the purpose

[Narretz]

The @knownIssue tag really serves a purpose, we can't just take it out. (if that is what you meant to do). We need to solve this issue at the template level, i.e. give @knownIssue a title parameter that is rendered as a heading only in the original document (because that's where you want the toc to actually contain it).

[kambleaa007]

Hello, I am new at open source contribution. @Narretz can you please guide me so i can contribute in documentation , I really like to.

[kambleaa007]

I thinks its very old issue.
With no one seems interested to help this issue.
Someone interested message here.

[petebacondarwin]

This is not a high priority for the project as it is now in LTS mode, and while not attractive the docs are usable.
Headings in the doc source are always a problem when you want to be able to render the content in different contexts. I am not sure what the best approach is for @knownIssue, since the heading for more complex known issues are very useful, but out of place in the overview table...