Menu
▾
▴
[cadcdev-svn-commits] [SCM] branch master updated. a11364a33bbd9fd5bbd40ba76743d2a8f0eb9cc0
|
From: quzar <qu...@us...> - 2024-10-10 11:09:04
|
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "A pseudo Operating System for the Dreamcast.".
The branch, master has been updated
via a11364a33bbd9fd5bbd40ba76743d2a8f0eb9cc0 (commit)
via a3344a04ff8bdc6e1d2f9b2a48a442bb786ddbfd (commit)
via 9c311e995eedead63761df6633cd91fbad0ea8d6 (commit)
via 51828c0430a67811a51e65968e6664c564d666fd (commit)
via d58c96531afa37472c0481881cd36da229a58c67 (commit)
via 988263c4633daac7e60eae8bb9224f8e268ede66 (commit)
via 2b84a77b08ceccc85b0bc5c0e844c3a34510611f (commit)
via 75528f147efafdec89d0e9c4adc120a368852b6c (commit)
via 60d5f0652b117bf4ce7922400b613b238df9d47f (commit)
via 71c9fc8677dac5bd61757da37368a2032eb15100 (commit)
via cae2bfcef1be5904277030d350628f68d115655b (commit)
via 42f52062fa39676d75b4d59d1be97b7fdf77a60c (commit)
via 1731eff6e4f865ac6037befb04f8b54b4927175a (commit)
via ea713ead89a1a140479721ecde68c0b7f466ca4a (commit)
via 3eac8bc7592faa9eacb29f18a94cabed961a8e81 (commit)
via 805da828bba4ccbbd029d9fb070a3e150eedf8a4 (commit)
via 93df6ff88880d15b803d108e8641ad5b7196efef (commit)
via d8bf22ad058c4058b09f58133929131a3bb3cf67 (commit)
via 5da9f618c9a52ff1e72d194bbdbadd078ebddb12 (commit)
via e13a8bb04d295e34d576d35b1cbcda0567954118 (commit)
via 59b1e327b8274c5b3bcc521911ffc065cd8c85e3 (commit)
from 5170f0311e07c888631138720cf1ee2673166586 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit a11364a33bbd9fd5bbd40ba76743d2a8f0eb9cc0
Merge: 5170f031 a3344a04
Author: Donald Haase <qu...@ya...>
Date: Thu Oct 10 07:07:17 2024 -0400
Merge pull request #759 from JoseAFRibeiro/doc
* Starting the doc guide draft
* Development of the documentation guidelines
* Description of the documentation levels
* Where to write what
* Style guide and some spelling
* information about useful doxygen command
---------
Co-authored-by: Falco Girgis <gyr...@gm...>
commit a3344a04ff8bdc6e1d2f9b2a48a442bb786ddbfd
Merge: 9c311e99 33b84c21
Author: Falco Girgis <gyr...@gm...>
Date: Sat Oct 5 10:15:49 2024 -0500
Merge branch 'master' into doc
commit 9c311e995eedead63761df6633cd91fbad0ea8d6
Author: Jose Ribeiro <jos...@gm...>
Date: Sat Oct 5 11:14:36 2024 +0100
information about useful doxygen command
commit 51828c0430a67811a51e65968e6664c564d666fd
Author: Jose Ribeiro <jos...@gm...>
Date: Sat Oct 5 11:00:09 2024 +0100
More spelling
commit d58c96531afa37472c0481881cd36da229a58c67
Author: Jose Ribeiro <jos...@gm...>
Date: Sat Oct 5 10:59:06 2024 +0100
Style guide and some spelling
commit 988263c4633daac7e60eae8bb9224f8e268ede66
Author: Jose Ribeiro <jos...@gm...>
Date: Sun Sep 15 12:46:30 2024 +0100
Little ajustments
commit 2b84a77b08ceccc85b0bc5c0e844c3a34510611f
Author: Jose Ribeiro <jos...@gm...>
Date: Sun Sep 15 12:43:43 2024 +0100
Where to write what
commit 75528f147efafdec89d0e9c4adc120a368852b6c
Author: Jose Ribeiro <jos...@gm...>
Date: Sun Sep 15 12:06:17 2024 +0100
Description of the documentation levels
commit 60d5f0652b117bf4ce7922400b613b238df9d47f
Author: Jose Ribeiro <jos...@gm...>
Date: Fri Sep 13 19:49:04 2024 +0100
Development of the documentation guidelines
commit 71c9fc8677dac5bd61757da37368a2032eb15100
Author: Jose Ribeiro <jos...@gm...>
Date: Thu Sep 12 21:44:12 2024 +0100
Starting the doc guide draft
commit cae2bfcef1be5904277030d350628f68d115655b
Merge: 42f52062 63b9b963
Author: José Ribeiro <602...@us...>
Date: Mon Sep 9 11:57:22 2024 +0100
Merge branch 'KallistiOS:master' into doc
commit 42f52062fa39676d75b4d59d1be97b7fdf77a60c
Merge: 1731eff6 002de35d
Author: José Ribeiro <602...@us...>
Date: Sun Aug 11 16:35:37 2024 +0100
Merge branch 'master' into doc
commit 1731eff6e4f865ac6037befb04f8b54b4927175a
Author: José Ribeiro <602...@us...>
Date: Sun Aug 11 16:16:01 2024 +0100
Update include/kos/fs_romdisk.h
Co-authored-by: Falco Girgis <gyr...@gm...>
commit ea713ead89a1a140479721ecde68c0b7f466ca4a
Author: Jose Ribeiro <jos...@gm...>
Date: Sun Aug 11 11:51:30 2024 +0100
Rewworking the line sizes
commit 3eac8bc7592faa9eacb29f18a94cabed961a8e81
Author: Jose Ribeiro <jos...@gm...>
Date: Sun Aug 11 11:49:28 2024 +0100
Explain how to build and embed fs image
commit 805da828bba4ccbbd029d9fb070a3e150eedf8a4
Author: José Ribeiro <602...@us...>
Date: Sun Aug 11 10:37:50 2024 +0100
Update include/kos/fs_romdisk.h
Co-authored-by: Falco Girgis <gyr...@gm...>
commit 93df6ff88880d15b803d108e8641ad5b7196efef
Author: Falco Girgis <gyr...@gm...>
Date: Thu Aug 8 08:28:35 2024 -0500
Update include/kos/fs_romdisk.h
Co-authored-by: Andy Barajas <and...@gm...>
commit d8bf22ad058c4058b09f58133929131a3bb3cf67
Author: José Ribeiro <602...@us...>
Date: Thu Jul 25 19:07:44 2024 +0100
Update include/kos/fs_romdisk.h
Co-authored-by: Andy Barajas <and...@gm...>
commit 5da9f618c9a52ff1e72d194bbdbadd078ebddb12
Author: José Ribeiro <602...@us...>
Date: Thu Jul 25 19:07:36 2024 +0100
Update include/kos/fs_romdisk.h
Co-authored-by: Andy Barajas <and...@gm...>
commit e13a8bb04d295e34d576d35b1cbcda0567954118
Author: José Ribeiro <602...@us...>
Date: Thu Jul 25 19:07:30 2024 +0100
Update include/kos/fs_romdisk.h
Co-authored-by: Andy Barajas <and...@gm...>
commit 59b1e327b8274c5b3bcc521911ffc065cd8c85e3
Author: Jose Ribeiro <jos...@gm...>
Date: Thu Jul 18 21:27:33 2024 +0100
Reworking FS driver explanation and size warning
-----------------------------------------------------------------------
Summary of changes:
doc/DOCGUIDE.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 113 insertions(+)
create mode 100644 doc/DOCGUIDE.md
diff --git a/doc/DOCGUIDE.md b/doc/DOCGUIDE.md
new file mode 100644
index 00000000..8d054db0
--- /dev/null
+++ b/doc/DOCGUIDE.md
@@ -0,0 +1,113 @@
+# Documentation Style Guide
+
+## A Guide For Writing and Reading KOS' Documentation
+
+### Documentation Structure
+
+KallistiOS uses Doxygen to generate documentation from the project's header
+files and the following .dox files:
+
+- attribution.dox
+- audio.dox
+- debugging.dox
+- filesystem.dox
+- math.dox
+- networking.dox
+- peripherals.dox
+- system.dox
+- threading.dox
+- timing.dox
+- video.dox
+
+All of them can be found in the doc folder.
+
+#### Topics
+
+Doxygen's documentation is organized in a tree-like structure constructed around
+Topics and Files. In KallistiOS, the previously mentioned list of files describes
+the top level Topics used to group the corresponding subtopics. As an example,
+the audio Topic hosts the Driver, Sound Effects and Streaming subtopics.
+Topics can link to Files and other topics as well.
+
+#### Files
+
+Files represent (optional) units of documentation that exist under Topics. Doxygen
+typically uses them to document specific source or header files. In KallistiOS,
+Files are used to list macros, function signatures, function lists and the
+headers used in the file.
+
+---
+
+### Documentation Level of Detail
+
+Different levels of detail are provided in KallistiOS' documentation as a way to
+help the reader quickly find their way through the documentation and the OS.
+To achieve these two goals, documentation should be written with more
+detail as it gets closer to the File level.
+
+Topic level documentation should aim to inform the reader of what they will find
+inside it. A top level Topic description must state the API's purpose and
+hardware it might relate to.
+
+Subtopics are the place to start providing more detailed insights into the API
+by describing its capabilities and limitations, providing function descriptions
+and alerting the reader to common pitfalls and known issues. Subtopics that
+aren't parents to other subtopics should also provide a basic guide into using
+the API, with a focus on any setup required to use it and its key
+functions.
+
+At the File level, the documentation should focus on describing the inner
+workings of a module as well as more advanced API use cases and data structures.
+
+#### Linking to Other Pages
+
+When expanding the documentation, it is good practice to provide links to
+important functions or macros mentioned. If a Topic has any type of relationship
+with resources that belong to another Topic, Doxygen functionalities should be
+used to ensure that the page points to the mentioned resources.
+This will help readers reach important pages that might be of their interest.
+
+---
+
+### Where to Write What
+
+Documentation should be kept in the header files of KallistiOS, while the .dox
+files should be used to define groups. As modern IDEs are capable of parsing
+Doxygen style documentation, keeping the majority of the documentation inside
+header files can prove useful for users as they use KallistiOS' APIs.
+
+In cases where a module has a top level header and then headers specific to
+other parts of the module, documentation should be kept on the specific header
+and then use Doxygen commands to present it on the top level header file, if
+needed. This allows for documentation to be kept in the corresponding header,
+maintaining the ability to use Doxygen's function specific functionalities
+without requiring a reorganising of function definitions inside the headers.
+
+---
+
+### Style Guide
+
+When contributing to the docs (either with new documentation or updates to
+existing docs), please make sure you follow this style guide so that everything
+stays uniform across pages.
+
+It is possible that chunks of code or documentation written in some header files
+belong on a different page than the one Doxygen is putting them on, but also contains
+information that, by virtue of providing IDEs information about the code, must not
+be moved. In these cases, Doxygen's `\addtogroup` allows writers to move documentation
+blocks around, without changing the header file where it is written
+
+#### Topic hierarchy
+
+Top level Topics are defined in their own text file in the `./doc/` folder; its in these files
+that their specific subtopics must be declared so that they can be referenced in the header files later.
+
+##### Functions
+
+When mentioned in the documentation, functions __must__ link back to their signatures.
+
+##### See Also
+
+Relevant macros or pages should be included in this section, so the reader can quickly move to pages that
+can be of interest. Structs are also good candidates to this section, as it often isn't possible to cover
+all of the thought that went into the members, alignments, padding and packing.
\ No newline at end of file
hooks/post-receive
--
A pseudo Operating System for the Dreamcast.
|
