1,847
edits
Project - Documentation: Difference between revisions
→Octave's internal documentation: Add description.
(→Octave's internal documentation: Add Resources section.) |
(→Octave's internal documentation: Add description.) |
||
| Line 58: | Line 58: | ||
=== Octave's internal documentation === | === Octave's internal documentation === | ||
[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: | |||
# Lack of developer knowledge (code grew over 25 years), many "cryptic" macros, very complex class inheritance trees: | |||
#* [https://octave.org/doxygen/5.2/d0/d26/classArray.html <code>liboctave/Array</code>] | |||
#* [https://octave.org/doxygen/5.2/d6/d68/classoctave__base__value.html <code>libinterp/octave_base_value</code>] | |||
# long build time to see results of documentation effort | |||
# huge size (about 2 GB), very impractical to "carry around", https://octave.org/doxygen slowly responding | |||
Nevertheless, there is a need for internal documentation: | |||
# Comprehensive documentation of Octave's [https://octave.org/doc/v5.2.0/External-Code-Interface.html external code interface]. | |||
# Enable newcomers (e.g. GSoC students) to study Octave's code easily. | |||
# 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. | |||
'''Resources''' | '''Resources''' | ||