nitdoc - Abstraction levels

[Morriar]

nitdoc - Abstraction levels

TODO

• [ ] Various levels of abstraction

  Clients require a high level of abstraction to understand the content and goals of an API. Based on the reader experience, various abstraction levels are needed. Newcomers do not need to see all the details. They would like to have enough information so that they can build a mental model of the system, and zoom on the specific details they are interested in.

• [ ] Lists and trees

  Lists are used to group a set of similar entities like classes or methods in a linear order, making it easy to read. Trees allow the representation of hierarchical entities like the classes contained in a package. Both offer a succinct presentation of the entity generally limited to a synopsis.

  Features

  • [ ] Reader end: sort & filter lists
  • [ ] Writter end: sort & filter lists
  • [ ] Automatic ranking, order suggestion, filter suggestion

• [ ] Diagrams and figures

  Automatically generated diagrams suffer from the same issues as automatic lists: The content is not filtered so the figures outputted can be hard to read or even hard to display in some browsers.

  Features

  • [ ] Reader end: filter figure (stdlib, more...)
  • [ ] Writter end: filter figure, suggest content (ranking)
  • [ ] More visual representation (#760, class blue-prints, WCG, #791)

• [ ] Source code presentation

  Code is the lowest level source of information that can be used. However, maintainers often try to avoid reading the source code, relying instead on more abstract software representations. So, documentation generators must also provide features to help such higher-level understanding.

  Features

  • [x] Fix #717
  • [x] Syntax highlighting
  • [ ] Code hyper-linking
  • [ ] Meaningfull blocks
  • [ ] Navigable call-graph
  • [ ] Codelets
  • [ ] Elucidative programming

Validation protocol

TODO

• [ ] Like for RI, precision & recall on figure contents
• [ ] Compare content against other ranking approach
• [ ] Expert validation

Also see

• [ ] Quality measures on graphical representations
• [ ] Cognitive approaches for content comprehension
• [ ] Visual learning and understanding

[privat]

Un lien a faire avec nituml ?

[Morriar]

Rajouté