From f910579e66a1495c4c1c97e2b99ea178d9d194ee Mon Sep 17 00:00:00 2001 From: pacien Date: Sat, 9 Dec 2017 01:59:50 +0100 Subject: Add proper struct documentation Signed-off-by: pacien --- doc/gen/Languages.txt | 118 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/gen/Topics.txt | 90 ++++++++++++++++++++++++++++++++++++ include/common/geom.h | 12 ++++- include/common/matrix.h | 6 ++- makefile | 6 +-- 5 files changed, 226 insertions(+), 6 deletions(-) create mode 100644 doc/gen/Languages.txt create mode 100644 doc/gen/Topics.txt diff --git a/doc/gen/Languages.txt b/doc/gen/Languages.txt new file mode 100644 index 0000000..9d0df2d --- /dev/null +++ b/doc/gen/Languages.txt @@ -0,0 +1,118 @@ +Format: 1.51 + +# This is the Natural Docs languages file for this project. If you change +# anything here, it will apply to THIS PROJECT ONLY. If you'd like to change +# something for all your projects, edit the Languages.txt in Natural Docs' +# Config directory instead. + + +# You can prevent certain file extensions from being scanned like this: +# Ignore Extensions: [extension] [extension] ... + + +#------------------------------------------------------------------------------- +# SYNTAX: +# +# Unlike other Natural Docs configuration files, in this file all comments +# MUST be alone on a line. Some languages deal with the # character, so you +# cannot put comments on the same line as content. +# +# Also, all lists are separated with spaces, not commas, again because some +# languages may need to use them. +# +# Language: [name] +# Alter Language: [name] +# Defines a new language or alters an existing one. Its name can use any +# characters. If any of the properties below have an add/replace form, you +# must use that when using Alter Language. +# +# The language Shebang Script is special. It's entry is only used for +# extensions, and files with those extensions have their shebang (#!) lines +# read to determine the real language of the file. Extensionless files are +# always treated this way. +# +# The language Text File is also special. It's treated as one big comment +# so you can put Natural Docs content in them without special symbols. Also, +# if you don't specify a package separator, ignored prefixes, or enum value +# behavior, it will copy those settings from the language that is used most +# in the source tree. +# +# Extensions: [extension] [extension] ... +# [Add/Replace] Extensions: [extension] [extension] ... +# Defines the file extensions of the language's source files. You can +# redefine extensions found in the main languages file. You can use * to +# mean any undefined extension. +# +# Shebang Strings: [string] [string] ... +# [Add/Replace] Shebang Strings: [string] [string] ... +# Defines a list of strings that can appear in the shebang (#!) line to +# designate that it's part of the language. You can redefine strings found +# in the main languages file. +# +# Ignore Prefixes in Index: [prefix] [prefix] ... +# [Add/Replace] Ignored Prefixes in Index: [prefix] [prefix] ... +# +# Ignore [Topic Type] Prefixes in Index: [prefix] [prefix] ... +# [Add/Replace] Ignored [Topic Type] Prefixes in Index: [prefix] [prefix] ... +# Specifies prefixes that should be ignored when sorting symbols in an +# index. Can be specified in general or for a specific topic type. +# +#------------------------------------------------------------------------------ +# For basic language support only: +# +# Line Comments: [symbol] [symbol] ... +# Defines a space-separated list of symbols that are used for line comments, +# if any. +# +# Block Comments: [opening sym] [closing sym] [opening sym] [closing sym] ... +# Defines a space-separated list of symbol pairs that are used for block +# comments, if any. +# +# Package Separator: [symbol] +# Defines the default package separator symbol. The default is a dot. +# +# [Topic Type] Prototype Enders: [symbol] [symbol] ... +# When defined, Natural Docs will attempt to get a prototype from the code +# immediately following the topic type. It stops when it reaches one of +# these symbols. Use \n for line breaks. +# +# Line Extender: [symbol] +# Defines the symbol that allows a prototype to span multiple lines if +# normally a line break would end it. +# +# Enum Values: [global|under type|under parent] +# Defines how enum values are referenced. The default is global. +# global - Values are always global, referenced as 'value'. +# under type - Values are under the enum type, referenced as +# 'package.enum.value'. +# under parent - Values are under the enum's parent, referenced as +# 'package.value'. +# +# Perl Package: [perl package] +# Specifies the Perl package used to fine-tune the language behavior in ways +# too complex to do in this file. +# +#------------------------------------------------------------------------------ +# For full language support only: +# +# Full Language Support: [perl package] +# Specifies the Perl package that has the parsing routines necessary for full +# language support. +# +#------------------------------------------------------------------------------- + +# The following languages are defined in the main file, if you'd like to alter +# them: +# +# Text File, Shebang Script, C/C++, C#, Java, JavaScript, Perl, Python, +# PHP, SQL, Visual Basic, Pascal, Assembly, Ada, Tcl, Ruby, Makefile, +# ActionScript, ColdFusion, R, Fortran + +# If you add a language that you think would be useful to other developers +# and should be included in Natural Docs by default, please e-mail it to +# languages [at] naturaldocs [dot] org. + + +Alter Language: C/C++ + + Struct Prototype Ender: ; diff --git a/doc/gen/Topics.txt b/doc/gen/Topics.txt new file mode 100644 index 0000000..c825869 --- /dev/null +++ b/doc/gen/Topics.txt @@ -0,0 +1,90 @@ +Format: 1.51 + +# This is the Natural Docs topics file for this project. If you change anything +# here, it will apply to THIS PROJECT ONLY. If you'd like to change something +# for all your projects, edit the Topics.txt in Natural Docs' Config directory +# instead. + + +# If you'd like to prevent keywords from being recognized by Natural Docs, you +# can do it like this: +# Ignore Keywords: [keyword], [keyword], ... +# +# Or you can use the list syntax like how they are defined: +# Ignore Keywords: +# [keyword] +# [keyword], [plural keyword] +# ... + + +#------------------------------------------------------------------------------- +# SYNTAX: +# +# Topic Type: [name] +# Alter Topic Type: [name] +# Creates a new topic type or alters one from the main file. Each type gets +# its own index and behavior settings. Its name can have letters, numbers, +# spaces, and these charaters: - / . ' +# +# Plural: [name] +# Sets the plural name of the topic type, if different. +# +# Keywords: +# [keyword] +# [keyword], [plural keyword] +# ... +# Defines or adds to the list of keywords for the topic type. They may only +# contain letters, numbers, and spaces and are not case sensitive. Plural +# keywords are used for list topics. You can redefine keywords found in the +# main topics file. +# +# Index: [yes|no] +# Whether the topics get their own index. Defaults to yes. Everything is +# included in the general index regardless of this setting. +# +# Scope: [normal|start|end|always global] +# How the topics affects scope. Defaults to normal. +# normal - Topics stay within the current scope. +# start - Topics start a new scope for all the topics beneath it, +# like class topics. +# end - Topics reset the scope back to global for all the topics +# beneath it. +# always global - Topics are defined as global, but do not change the scope +# for any other topics. +# +# Class Hierarchy: [yes|no] +# Whether the topics are part of the class hierarchy. Defaults to no. +# +# Page Title If First: [yes|no] +# Whether the topic's title becomes the page title if it's the first one in +# a file. Defaults to no. +# +# Break Lists: [yes|no] +# Whether list topics should be broken into individual topics in the output. +# Defaults to no. +# +# Can Group With: [type], [type], ... +# Defines a list of topic types that this one can possibly be grouped with. +# Defaults to none. +#------------------------------------------------------------------------------- + +# The following topics are defined in the main file, if you'd like to alter +# their behavior or add keywords: +# +# Generic, Class, Interface, Section, File, Group, Function, Variable, +# Property, Type, Constant, Enumeration, Event, Delegate, Macro, +# Database, Database Table, Database View, Database Index, Database +# Cursor, Database Trigger, Cookie, Build Target + +# If you add something that you think would be useful to other developers +# and should be included in Natural Docs by default, please e-mail it to +# topics [at] naturaldocs [dot] org. + + +Topic Type: Struct + + Plural: Structs + Class Hierarchy: Yes + + Keywords: + struct diff --git a/include/common/geom.h b/include/common/geom.h index 4445998..a843c76 100644 --- a/include/common/geom.h +++ b/include/common/geom.h @@ -15,16 +15,24 @@ typedef int32_t IntVector; /** - * Type: CartesianVector + * Struct: CartesianVector * An abstract 2-D vector in cartesian coordinates. + * + * Fields: + * x - the horizontal component + * y - the vertical component */ typedef struct { IntVector x, y; } CartesianVector; /** - * Type: CartesianMapping + * Struct: CartesianMapping * A tuple of cartesian vectors representing a mapping. + * + * Fields: + * origin - preimage vector + * target - image vector */ typedef struct { CartesianVector origin, target; diff --git a/include/common/matrix.h b/include/common/matrix.h index 726a8ab..fe4a12a 100644 --- a/include/common/matrix.h +++ b/include/common/matrix.h @@ -12,8 +12,12 @@ #include "geom.h" /** - * Type: IntSquareMatrix + * Struct: IntSquareMatrix * Represents a square integer matrix. + * + * Fields: + * **elements - NULL-terminated array of element pointers + * dim - dimension */ typedef struct { IntVector **elements; diff --git a/makefile b/makefile index 7ee5ee7..eba11f6 100644 --- a/makefile +++ b/makefile @@ -57,9 +57,9 @@ clean-bin: .PHONY: api-doc clean-api-doc api-doc: - $(eval TMPDIR := $(shell mktemp -d)) - naturaldocs --project $(TMPDIR) --input $(INCLUDE_DIR) --input $(DOC_DIR)/topics/ --output HTML $(DOC_DIR)/api/ - $(RM) -r $(TMPDIR) + naturaldocs --project $(DOC_DIR)/gen/ --output HTML $(DOC_DIR)/api/ \ + --input $(INCLUDE_DIR) --input $(DOC_DIR)/topics/ + $(RM) $(DOC_DIR)/gen/Menu.txt clean-api-doc: $(RM) -r $(DOC_DIR)/api/* -- cgit v1.2.3 From 7beb6bfadb504f8d1d7c1d069986e9eb9cd32673 Mon Sep 17 00:00:00 2001 From: pacien Date: Sat, 9 Dec 2017 02:48:14 +0100 Subject: Rename phony targets Signed-off-by: pacien --- makefile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/makefile b/makefile index eba11f6..33706f3 100644 --- a/makefile +++ b/makefile @@ -18,15 +18,15 @@ PERCENT := % ##### MAIN TARGETS -.PHONY: all test source report clean +.PHONY: all check build report clean -all: source test api-doc report; +all: build check api-doc report; .SECONDEXPANSION: -source: $$(patsubst $(SRC_DIR)/$$(PERCENT).c,$(BIN_DIR)/$$(PERCENT).o,$$(wildcard $(SRC_DIR)/**/*.c)); +build: $$(patsubst $(SRC_DIR)/$$(PERCENT).c,$(BIN_DIR)/$$(PERCENT).o,$$(wildcard $(SRC_DIR)/**/*.c)); .SECONDEXPANSION: -test: $$(patsubst $(TEST_DIR)/$$(PERCENT).c,$(BIN_DIR)/$$(PERCENT).test,$$(wildcard $(TEST_DIR)/**/*.c)); +check: $$(patsubst $(TEST_DIR)/$$(PERCENT).c,$(BIN_DIR)/$$(PERCENT).test,$$(wildcard $(TEST_DIR)/**/*.c)); report: $(DOC_DIR)/project-report.pdf; @@ -42,7 +42,7 @@ $(BIN_DIR)/%.o: $$(patsubst $(BIN_DIR)/$$(PERCENT).o,$(SRC_DIR)/$$(PERCENT).c,$$ $(CC) $(CFLAGS) $(IFLAGS) -c $< -o $@ .SECONDEXPANSION: -$(BIN_DIR)/%.test: $$(patsubst $(BIN_DIR)/$$(PERCENT).test,$(TEST_DIR)/$$(PERCENT).c,$$@) source | $$(@D)/ +$(BIN_DIR)/%.test: $$(patsubst $(BIN_DIR)/$$(PERCENT).test,$(TEST_DIR)/$$(PERCENT).c,$$@) build | $$(@D)/ $(CC) $(CFLAGS) $(IFLAGS) $(BIN_DIR)/**/*.o $< -o $@ $(LFLAGS) ./$@ -- cgit v1.2.3