documentation
#define documentation: \
I-------------------------------------------------------------------------\
I ______ _ _ _ \
I | _ \ | | | | (_) \
I | | | |___ ___ _ _ _ __ ___ ___ _ __ | |_ __ _| |_ _ ___ _ __ \
I | | | / _ \ / __| | | | '_ ` _ \ / _ \ '_ \| __/ _` | __| |/ _ \| '_ \ \
I | |/ / (_) | (__| |_| | | | | | | __/ | | | || (_| | |_| | (_) | | | | \
I |___/ \___/ \___|\__,_|_| |_| |_|\___|_| |_|\__\__,_|\__|_|\___/|_| |_| \
I-------------------------------------------------------------------------I
https://diataxis.fr/
" \
Briefly stated, the Gell-Mann Amnesia effect is as follows. You open the \
newspaper to an article on some subject you know well. In Murray's case, \
physics. In mine, show business. You read the article and see the journalist \
has absolutely no understanding of either the facts or the issues. Often, \
the article is so wrong it actually presents the story backward—reversing \
cause and effect. I call these the 'wet streets cause rain' stories. Paper's \
full of them. \
\
In any case, you read with exasperation or amusement the multiple errors in a \
story, and then turn the page to national or international affairs, and read \
as if the rest of the newspaper was somehow more accurate about Palestine \
than the baloney you just read. You turn the page, and forget what you know. \
"
○ types
• most projects either only write one type and call it a day
or worse, mix them into a borderline useless gray glob
developer - explains how to implement
guide - explains how to read/navigate
teaching - explains how to use
reference - lists dry facts for quick look ups of details
Specifications: Specifications:
• formal outline and definition of a project
• the contents define what constitutes as a specification, the format is rougly free form
• falls into the category of developer documentation
Script:
• not related to executable scripts
• branching flow chart of usage
• meant to simulate the end product in action
PRD:
• "Product Requirements Documentation"
— attempt to answer the following questions regarding the software:
• what will the software be used for?
• what is currently in place?
• how would the ideal usage look like?
• what features are necessary?
• what are the related legal requirements/restrictions?
• what alien concepts will the programmers have to get familiar with?
Functional_specification:
• a PRD which defines an interface {commandline args; gui map} for each function
• often there is a separate PRD and a functional specification building on it
• includes schematics for all required databases
• often has screen designs attached
System_specification:
• analyses feasibility
• analyses risk
• mentions concrete technologies and work methods to be used
• a system specification which ignores physical constraints {bandwidth; processing power} is called a logical system specification
• a system specification explicit-ly distanced from a logical system specification is referred to as a physical system specification
• commonly contains figures {UML}
Decision_table:
https://www.hillelwayne.com/post/decision-table-patterns/
• "Parnas table"
• maps enum inputs to a finite set of arbitrary outputs
• rows should be ordered by the left most column values
• its complete if every input combination is added as a row
• a catch all value can be represented with '-' or '_' as long as it doesnt introduce row precedence
• '/' can be used to signal a nonsensical value (state)
{
--------------------------
| In1 | In2 || Out |
--------------------------
| false | false || false |
| false | true || true |
| true | false || true |
| true | true || false |
--------------------------
}
Inline: Inline:
• in most cases it means "fancy comments with special importance"
Traditional:
• typically seen in legacy C and similarly old code
: placed after non-returning calls inside blocks
: leaves an explicitly important comment on a piece code
: signals that something regarding a specific piece of should be done
: signals that something regarding a specific piece of should be done
: really verbose while(true)
C#:
• Microsoft's invention/convention
• documentation is embedded into the code via comments using XML (see "/XML")
• some editors (Visual Studio) parse them to provide live tool-tips
• valid after 3 '/'s
• C# only
• restrictive
• xml
Tags:
Main:
• field to store meaningful information
<summary>
<remarks>
<param name="<parameter_name>">
<returns>
<example>
Cosmetic:
• used for structuring/highlighting/etc. main tags
<paramref name="<parameter_name>">
<para> : <p>
<code>
<returns>
{
public int Add(int a, int b){
return a + b;
}
}
Doxygen:
• used by the Doxygen documentation generation tool
• for mainstream imperative languages
• restrictive
Tags:
@brief
@param
@return
@see
@warning
@note
Natural_docs:
https://naturaldocs.org/
• natural looking; clean
• general purpose; extendable
• its packaging and linux support is fucked because C# & windows people
Wiki: Wiki:
• umbrella term any collection of notes
• this document itself constitutes as a personal wiki
— numerious wiki-engines exists:
• which allow rendering dialects of the so called wikitext markup language
• which help taking notes as a group
• the popular choice is mediawiki
• to effectively manage and navigate a wiki, a Table of Contents is required;
for this reason you are advised to use a wiki-engine, LaTeX, or roll your own markup
— Obsidian:
https://obsidian.md/
• popular choice for creating personal wiki-s
• doesnt scale well
DBML: DBML:
• "DataBase Markup Language"
• used for describing database structures
• the primary goal is to create visual documentation (generate images)
— rant:
• I'm so mad
• we already have a language for this: SQL
• if you want extra styling information,
make it a super set of SQL and have an include directive,
or use magick comments
• "database agnostic", yeah, well, so is my cock,
but only because they have no interoperation what-so-ever
• there are conversion tools! meaning they already wrote something that can parse SQL!
• the only thing this accomplishes is duplication
UML: UML:
https://plantuml.com/class-diagram#4b62dd14f1d33739
• "Unified Modelling Language"
• markup language describing objects and relations
Programs:
plantuml [options] [file] : used for creating images from uml code
• piggybacks graphviz; dot notation is exposed (see BELOW)
Extensions:
.uml
.puml
Comments:
• retarded C/C++
' single line comment
/' multiline comment '/
Body:
@startuml
<...>
@enduml
@startdot
<graphviz dot notation>
@enddot
Containers:
<typename> <name> { [object]* }
typename:
package
folder
cloud
database
node
frame
rectangle
Objects:
<typename> <name> { [body] }
typename:
object
class
struct
interface
abstract
entity
enum
metaclass
protocol
stereotype
annotation
exception
circle
diamond
body:
member:
[access]<string>
• types are usually represented as pseudo-code syntax in <string>
• if <string> has a '(' it will be considered a member function,
which affects rendering
{ separation from fields; different access symbols }
access:
+ public
— private
# protected
~ module private
separator:
<line>
<line> string <line>
• creates a horizontal line, optionally with text
• intended to separate groups of related members
line:
--
==
..
__
Relations:
<object-1> <relation-type> <object-2> (: ([-])<comment-string>)
relations-type:
[arrow-head]<line>[arrow-head]
line:
-- : continous
.. : dotted
arrow-head:
• : simple/dependency
|> : extension/inheritance
* : composition
o : aggregation
} : to many
#
x
+
• the '>' and "|>" heads must face the "correct" way
• if the objects are not declared, they will default to empty class-es
Notes:
note <left|right|top|bottom> of <object> : <string>
• adds an arbitrary comment to an object
• '\n' can be used inside <string> to break into a new line
Markup:
<b>
<u>
<i>
<s>
<del>
<strike>
<font color="#AAAAAA">
<font color="colorName">
<color:#AAAAAA>
<color:colorName>
<size:int> to change font size
<img src="file">
<img:file>
Skins:
skin <name>
• controls the style of the elements
Conventional_commits: Conventional_commits:
• recommended way of writting commit messages
• very pleasent to read
• could allow for automation
{
<typename>[(scope)][!]: <description>
[body]
}
{
feat(cli)!: remade from scratch
you must understand, i was very bored
}
typename:
feat - new feature
refactor - code change that does (should) not affect behaviour
fix - bug fix
docs - hand written documentation
test - new or modified tests
perf - performace increase
chore - meta task {build system; project struct}
ci - continous integration task
build - build system task
style - coding style fix
scope:
• signals what part(s) of the code are affected
!:
• signals a breaking change
— can be used for auto versioning
fix - PATCH
feat - MINOR
! - MAJOR
Md2man:
markdown
man
• markdown is significantly nicer to read and write as plain-text than roff,
but we live in the dark ages so the man system cannot automatically render md
go-md2man : most trusty implementation
kramdown-man : slightly sloppy implementation;
supports auto launching man on non-saved outputs
ts-md2man : tree-sitter based, unstable implementation
w2m:
• "word to man"
• attempts to convert microsoft word documents to markdown
man
#define man:: \
__ __ \
| \/ |__ _ _ _ \
| |\/| / _` | ' \ \
|_| |_\__,_|_||_| I
• "MANual"
• an ecosystem of documentation, tools and conventions
• uses the God aweful groff format; it could just support markdown,
but we live in the dark ages
Files:
/usr/share/man/ : man file location
Pages:
• manuals are organized into so called pages
• each page represents a general category
• used for mitigating name collisions in a generalized way
• arbitrary pages are allowed
1 - Executable programs or shell commands
2 - System calls (functions provided by the kernel)
3 - Library calls (functions within program libraries)
4 - Special files (usually found in /dev)
5 - File formats and conventions, e.g. /etc/passwd
6 - Games
7 - Miscellaneous {macro packages; conventions}
8 - System administration commands (usually only for root)
9 - Kernel routines [Non standard]
<...> - not standard;
the author couldn't organize it better and said "fuck it";
your best guess is its name
n - like ABOVE, but the author didnt even try
Programs:
whatis [program] : display one-line manual page descriptions;
totally useless in practice;
the main problem seems to be
that not many manpages obey
the guidelines
so there's no whatis description
in them to extract
man [page] <name> : outputs manual (ie. man page) for <name>
Links:
<name>(<int>)
• points to another man page
• man pages have them scattered all around as tips for further reading
• conventionally there is a large "See Also" dump at the end
{
"capabilities(7)"
$ man 7 capabilities
"stat(3type)"
$ man 3type stat
}
mandb : creates or updates man page index caches;
this includes whatis (see ABOVE) entries
Environment:
MANPATH : manual search path
MANPAGER : pager to use for displaying man pages
info
#define info:: \
___ __ \
|_ _|_ _ / _|___ \
| || ' \| _/ _ \ \
|___|_||_|_| \___/ \
• "gnu texINFO system"
• failed man replacement
• GNU brainrot
• roughly derived from TeX
Programs:
info [options] <subject>
--vi-keys
markdown
#define markdown:: \
__ __ _ _ \
| \/ |__ _ _ _| |____| |_____ __ ___ _ \
| |\/| / _` | '_| / / _` / _ \ V V / ' \ \
|_| |_\__,_|_| |_\_\__,_\___/\_/\_/|_||_| I
• markup language which is aimed to be legible both in plain-text an rendered
• by processing and converting, can represent almost whatever kind of document
• graphical git repository servers often display a repository's "README.md" by default;
has become an industry standard
Features:
• chars with special meaning can be escaped (with a '\\' char)
# [Heading name] ([ID]) : creates the largest possible heading
## [Heading name] ([ID]) : creates a smaller heading
### [Heading name] ([ID]) : creates a smaller heading
#### [Heading name] ([ID]) : creates a smaller heading
##### [Heading name] ([ID]) : creates a smaller heading
###### [Heading name] ([ID]) : creates a smallest possible heading
{#[name]} : creates ID with [name]
*<string>* || _<string>_ : makes <string> italic
**<string>** || __<string>__ : makes <string> bold
***<string>*** || ___<string>___: makes <string> bold and italic
~~<string>~~ : makes <string> strikethrough
. --- || ___ || *** : horizontal line
• <string> : creates block qoute; can be nested
Links:
[<string>](#[ID]) : creates link to header with [ID]
[<string>]([link]) : creates link to [link] with <string> as its visible text
[<string>][[label]] [...] [[label]]: <[link]> : creates link to [link] with <string> as its visible text; defined at [label]
 : soft links to media at [path]
Lists:
• can be nested
Ordered:
• the processed numbers will always be in acendig order
• must start with one; the numbers following it DOESNT effect the order
1. [first element]
[num]. [second element]
[...]
[num]. [n-th element]
Unordered:
• prefix the line with any of the following chars and a space:
*
+
—
• mixing is allowed
Definition:
[term]
: [definition]
Tasks:
— [[X|' ']] <string> : creates tast; X marks its comleated ' ' marks its not compleated
Tables:
• use 3 '-'-s or more to create a column header
• use '|'-s to separate column
• align to left, right or center by adding a ':' to the left, right or on both sides of the '-'-s of the header row
{
| color | symbolism |
| :---: | :---: |
| blue | water |
| red | blood |
}
Footnotes:
[...][^[identifier]] [...] [^[identifier]]: [...]
• clickable
• identifiers can contain numbers and letters, but not white spaces
Code:
{
this is code
}
• anything indented
Notes:
[
]
Extensions:
Fenced_code_blocks:
{
```[language]
this is also code;
the [language] could be C for example
```
}
• alternative way to add code
• plays better with highlighting (its easier for renderers to support it)
Github_flavour:
• "github dialect"
• fenced codeblocks
• bunch of horrific html shit no one cares about
alerts:
{
• [!<alert_type>]
• <...>
}
• special block quotes with special rendering
alert_types:
NOTE
TIP
IMPORTANT
WARNING
CAUTION