Ideas for the documentation system and browser
Brought to you by:
fnch
Menu
▾
▴
#12 Ideas for the documentation system and browser
- The documentation system should allow specifying some code-snippets, which can be pasted - using the documentation browser - into the current document. During paste the documentation browser should expand macros like (**dox-new-point: (1.23, 4.56), "description"*) in a convenient way. In this particular case, the point should be added and its name should be used to expand the macro. As a further extension, Boxer may decide to interact with the user, tell him/here that the selected object requires one point to be created and ask him/her to create it. This could provide a very powerful way to extend the Boxer GUI. This would be nicer if Boxer could analyse the code, see where the cursor is, understand whether we are inside a box construct which allows the given object to be used. If this is the case then the object can be simply pasted (e.g. "Object[...]"), otherwise a variable should be created (e.g. "object1 = Object[...]") or the object should be ignored (e.g. "\ Object[...]").
- The documentation system should allow to specify, for the object which is being documented, some code snippets which provide an example of usage. These examples should be shown in the documentation browser.
- The documentation browser should be able to show information about errors in parsing the documentation.
- The documentation browser should allow inspecting the source code which defines the selected object.
Further ideas:
- adding icons to distinguish different types of documentation entries in the tree-view: types, subtypes, instances, sections.
- add a button to re-build documentation.
- add an entry which allows including the current file in the groups of documentation files.
Some more things:
- adjust the example section so that we can include real code snippets (similarly to the "Preview" blocks)
- make sure that the page for sections are shown when selecting them on the tree-view
- make sure error in documentation parsing do not crash the whole GUI