281
edits
Project - Documentation: Difference between revisions
Jump to navigation
Jump to search
m
→Suggested Projects
| Line 61: | Line 61: | ||
'''Description''' | '''Description''' | ||
[https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen], and [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] for | [https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen], and [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] for its internal documentation. There has been only 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: | # 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/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>] | #* [https://octave.org/doxygen/5.2/d6/d68/classoctave__base__value.html <code>libinterp/octave_base_value</code>] | ||
# long Doxygen build time to see results of documentation effort | # long Doxygen build time to see results of documentation effort | ||
# huge size (about 2 GB), very impractical to "carry around", https://octave.org/doxygen slowly responding | # huge size (about 2 GB), very impractical to "carry around", [https://octave.org/doxygen] slowly responding | ||
Nevertheless, there is a need for internal documentation: | Nevertheless, there is a need for internal documentation: | ||
| Line 77: | Line 77: | ||
* 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)]): | * 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, ...). | ** Overview about the code base (liboctave, libinterp, libgui, ...). | ||
** How Octave is | ** How Octave is built (necessary tools [versions], involved scripts, ...). | ||
** The release procedure, e.g. [[6.1 Release Checklist]]. | ** The release procedure, e.g. [[6.1 Release Checklist]]. | ||
* Make the internal documentation '''obvious, easy to study and to extend, avoid effort duplication'''. | * Make the internal documentation '''obvious, easy to study and to extend, avoid effort duplication'''. | ||
| Line 87: | Line 87: | ||
** Fast build time. | ** Fast build time. | ||
** Lightweight (existing) documentation system. No heavy preprocessing / code generation by custom scripts. | ** Lightweight (existing) documentation system. No heavy preprocessing / code generation by custom scripts. | ||
** As close to the source as necessary. Make it difficult to update the code while not updating | ** As close to the source as necessary. Make it difficult to update the code while not updating its documentation. E.g. no wiki documentation for Octave's C++ files. | ||
'''Resources''' | '''Resources''' | ||