1,847
edits
Project - Documentation: Difference between revisions
→Octave's internal documentation: Suggested improvements.
(→Octave's internal documentation: Add description.) |
(→Octave's internal documentation: Suggested improvements.) |
||
| Line 57: | Line 57: | ||
=== Octave's internal documentation === | === Octave's internal documentation === | ||
'''Description''' | |||
[https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen] for it's internal documentation. Ever since, there has been moderate effort to add Doxygen comments to the entire code base or to create verbose descriptions for key techniques about how Octave works (here an example for [https://octave.org/doxygen/5.2/df/d4d/Macros.html important Octave macros]). Potential reasons for this circumstance are: | [https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen] for it's internal documentation. Ever since, there has been moderate effort to add Doxygen comments to the entire code base or to create verbose descriptions for key techniques about how Octave works (here an example for [https://octave.org/doxygen/5.2/df/d4d/Macros.html important Octave macros]). Potential reasons for this circumstance are: | ||
| Line 70: | Line 72: | ||
# Avoid knowledge drain ([https://en.wikipedia.org/wiki/Bus_factor bus factor]). | # Avoid knowledge drain ([https://en.wikipedia.org/wiki/Bus_factor bus factor]). | ||
As Octave's GUI makes use of qt, Doxygen might also be replaced by [https://doc.qt.io/qt-5/qdoc-index.html QDoc] with comparable markup. | '''Improvements''' | ||
* The internal documentation should cover the following topics (a more verbose extension of [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] [https://octave.org/doxygen/5.2/d1/d10/Hacking.html (html)]): | |||
** Overview about the code base (liboctave, libinterp, libgui, ...). | |||
** How Octave is build (necessary tools [versions], involved scripts, ...). | |||
** The release procedure, e.g. [[6.1 Release Checklist]]. | |||
* Make the internal documentation '''obvious, easy to study and to extend, avoid effort duplication'''. | |||
** The internal documentation should not be fixed on Doxygen comments only. | |||
** As Octave's GUI makes use of qt, Doxygen might also be replaced by [https://doc.qt.io/qt-5/qdoc-index.html QDoc] with comparable markup. | |||
** Splitting the documentation into a wiki portion, etc., is imaginable, but it must be clearly documented where to find which information, '''avoid duplication''', nobody wants to update information in more than one location. | |||
'''Resources''' | '''Resources''' | ||