Skip to content

Commit

Permalink
[doc] Improve class documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@IceflowRE
IceflowRE committed Jun 24, 2024
1 parent d364ac1 commit 24a39ff
Show file tree
Hide file tree
Showing 13 changed files with 192 additions and 141 deletions.
4 changes: 4 additions & 0 deletions doc/docs/_static/css/common.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,7 @@
width: 100%;
text-align: center;
}

.kny-mono-font {
font-family: var(--md-code-font-family);
}
3 changes: 3 additions & 0 deletions doc/docs/_static/css/godot_ref.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.kny-godot-ref {
font-family: var(--md-code-font-family);
}
2 changes: 1 addition & 1 deletion doc/docs/addons/aspect_ratio_resize_container.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ This works except for `STRETCH_MODE_COVER`.

## Example

{{ kny:source /examples/aspect_ratio_resize_container/ }}
{{ kny:source "/examples/aspect_ratio_resize_container/" }}

## Changelog

Expand Down
2 changes: 1 addition & 1 deletion doc/docs/addons/custom_theme_overrides.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The custom theme override variables can be handled like every other theme overri

## Example

{{ kny:source /examples/custom_theme_overrides/ }}
{{ kny:source "/examples/custom_theme_overrides/" }}

```gdscript
# declare the members
Expand Down
2 changes: 1 addition & 1 deletion doc/docs/addons/git_sha_project_setting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The Git SHA will **not** be kept in `project.godot` to not clutter any version c

## Example

{{ kny:source /examples/git_sha_project_setting/ }}
{{ kny:source "/examples/git_sha_project_setting/" }}

## Changelog

Expand Down
55 changes: 33 additions & 22 deletions doc/docs/addons/glogging.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ Logging into a file is not supported. The output will be always done via print.
## Compatibility

| Godot | Version |
|-------|----------|
| ----- | -------- |
| 4.3 | >= 1.5.0 |
| 4.2 | >= 1.5.0 |
| 4.1 | <= 1.4.1 |

## Example

{{ kny:source /examples/glogging/ }}
{{ kny:source "/examples/glogging/" }}

Example output.

Expand All @@ -35,72 +35,83 @@ Example output.

### GLogging

{{ kny:source /addons/glogging/glogging.gd res://addons/glogging/glogging.gd }}
{{ kny:source "/addons/glogging/glogging.gd" "res://addons/glogging/glogging.gd" }}

Logging base class. Provides helper methods.

#### Properties

| Name | Type | Description |
|-------------|---------------------------|---------------------|
| root_logger | [Logger](#glogginglogger) | root logger object. |
| Name | Type | Description |
| ------------------------------- | ------------------------- | ------------------- |
| root_logger {: .kny-mono-font } | [Logger](#glogginglogger) | root logger object. |

#### Constants

| Name | Type | Value | Description |
| -------------------------------- | ------------------- | ----- | ------------------- |
| LEVEL_NOTSET {: .kny-mono-font } | {{ kny:godot int }} | 0 | Logging level not set. |
| LEVEL_DEBUG {: .kny-mono-font } | {{ kny:godot int }} | 10 | |
| LEVEL_INFO {: .kny-mono-font } | {{ kny:godot int }} | 20 | |
| LEVEL_WARNING {: .kny-mono-font } | {{ kny:godot int }} | 30 | |
| LEVEL_ERROR {: .kny-mono-font } | {{ kny:godot int }} | 40 | |
| LEVEL_CRITICAL {: .kny-mono-font } | {{ kny:godot int }} | 50 | |

#### Methods

`debug(message: Variant, values: Array[Variant] = []) -> void`
void debug ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values ) const {: .kny-mono-font }
: log with root logger at debug level

`info(message: Variant, values: Array[Variant] = []) -> void`
void info ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values ) const {: .kny-mono-font }
: log with root logger at info level

`warning(message: Variant, values: Array[Variant] = []) -> void`
void warning ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values ) const {: .kny-mono-font }
: log with root logger at warning level, will also display a debug warning

`error(message: Variant, values: Array[Variant] = []) -> void`
void error ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values ) const {: .kny-mono-font }
: with root logger at error level, will also display a debug error

`critical(message: Variant, values: Array[Variant] = []) -> void`
void critical ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values ) const {: .kny-mono-font }
: log with root logger at critical level

`log(level: int, message: Variant, values: Array[Variant] = []) -> void`
void log ( {{ kny:godot int }} level, {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values ) const {: .kny-mono-font }
: log at a custom level

### GLogging.Logger

{{ kny:badge extends RefCounted }}

{{ kny:source /addons/glogging/glogging.gd res://addons/glogging/glogging.gd }}
{{ kny:source "/addons/glogging/glogging.gd" "res://addons/glogging/glogging.gd" }}

Logger class.
If not log level is set, the log level of the parent logger will be used.

#### Methods

`create_child(module_name: String, log_level: int = LEVEL_NOTSET) -> Logger`
[Logger](#glogginglogger) create_child ( {{ kny:godot String }} module_name, {{ kny:godot int }} log_level=LEVEL_NOTSET) const {: .kny-mono-font }
: create a child logger

`set_log_level(level: int) -> void`
void set_log_level ( {{ kny:godot int }} level ) {: .kny-mono-font }
: set the log level

`log_level() -> int`
{{ kny:godot int }} log_level () const {: .kny-mono-font }
: get log level

`debug(message: Variant, values: Array[Variant] = []) -> void`
void debug ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values) const {: .kny-mono-font }
: log at debug level

`info(message: Variant, values: Array[Variant] = []) -> void`
void info ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values) const {: .kny-mono-font }
: log at info level

`warning(message: Variant, values: Array[Variant] = []) -> void`
void warning ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values) const {: .kny-mono-font }
: log at warning level, will also display a debug warning

`error(message: Variant, values: Array[Variant] = []) -> void`
void error ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values) const {: .kny-mono-font }
: log at error level, will also display a debug error

`critical(message: Variant, values: Array[Variant] = []) -> void`
void critical ( {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values) const {: .kny-mono-font }
: log at critical level

`log(level: int, message: Variant, values: Array[Variant] = []) -> void`
void log ( {{ kny:godot int }} level, {{ kny:godot Variant }} message, {{ kny:godot Array }}[{{ kny:godot Variant }}]=[] values) const {: .kny-mono-font }
: log at custom level

## Changelog
Expand Down
2 changes: 1 addition & 1 deletion doc/docs/addons/hide_private_properties.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ This plugin will hide exported private properties in the inspector for instantia

## Example

{{ kny:source /examples/hide_private_properties/ }}
{{ kny:source "/examples/hide_private_properties/" }}

## Changelog

Expand Down
91 changes: 53 additions & 38 deletions doc/docs/addons/licenses.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ project settings under the menu `Plugins` -> `Licenses`.
## Compatibility

| Godot | Version |
|-------|---------------|
| ----- | ------------- |
| 4.3 | >= 1.8.0 |
| 4.2 | 1.6.0 - 1.7.8 |
| 4.1 | <= 1.5.0 |
Expand All @@ -25,42 +25,57 @@ project settings under the menu `Plugins` -> `Licenses`.

## Example

{{ kny:source /examples/licenses/ }}
{{ kny:source "/examples/licenses/" }}

## Interface

### Licenses

{{ kny:source /addons/licenses/licenses.gd res://addons/licenses/licenses.gd }}
{{ kny:source "/addons/licenses/licenses.gd" "res://addons/licenses/licenses.gd" }}

Providing static utility and static functions to save and load licenses.

#### Methods

`static compare_components_ascending(lhs: Component, rhs: Component) -> bool`
{{ kny:godot bool }} compare_components_ascending ( [Component](#component) lhs, [Component](#component) rhs ) static {: .kny-mono-font }
: Compare components ascending.

`static get_engine_component(name: String) -> Component`
[Component](#component) get_engine_component ( {{ kny:godot String }} name ) static {: .kny-mono-font }
: Get engine component by name.

`static get_engine_components() -> Array[Component]`
{{ kny:godot Array }}[[Component](#component)] get_engine_components () static {: .kny-mono-font }
: Get all engine components.

`static get_required_engine_components() -> Array[Component]`
{{ kny:godot Array }}[[Component](#component)] get_required_engine_components () static {: .kny-mono-font }
: Get engine components which are marked as required to mention.

`static save(components: Array[Component], file_path: String) -> int`
{{ kny:godot int }} save ( {{ kny:godot Array }}[[Component](#component)] components, {{ kny:godot String }} file_path ) -> static {: .kny-mono-font }
: Save array of components to file.

`static load(file_path: String) -> LoadResult`
[LoadResult](#licensesloadresult) load ( {{ kny:godot String }} file_path ) static {: .kny-mono-font }
: Load licenses from file.

`static set_license_data_filepath(path: String) -> void`
void set_license_data_filepath ( {{ kny:godot String }} path ) static {: .kny-mono-font }
: Set the project license data path.

`static get_license_data_filepath() -> String`
{{ kny:godot String }} get_license_data_filepath () static {: .kny-mono-font }
: Returns the project license data path.

### Licenses.LoadResult

{{ kny:badge extends RefCounted --left-bg }}

{{ kny:source "/addons/licenses/licenses.gd" "res://addons/licenses/licenses.gd" }}

Loading result returned when loading a licenses file.

#### Properties

| Name | Type | Description |
| ------------------------------ | ---------------------------------------------- | ---------------------------------- |
| components {: .kny-mono-font } | {{ kny:godot Array }}[[Component](#component)] | Components. |
| err_msg {: .kny-mono-font } | {{ kny:godot String }} | Error message when loading failed. |

### Component

{{ kny:badge extends RefCounted --left-bg }}
Expand All @@ -71,31 +86,31 @@ Component class, data wrapper for all information regarding one license item.

#### Properties

| Name | Type | Description |
|-------------|---------------------------------------|----------------------------------------------------------------------------|
| id | String | Identifier. |
| category | String | Use to structure the licenses to top categories. E.g. Textures, Fonts, ... |
| name | String | Name of the software or component. |
| version | String | Version of the software or component. |
| copyright | PackedStringArray | Copyrights. |
| contact | String | Contact of developer. |
| description | String | Additional description. |
| web | String | Web url to project page. |
| paths | PackedStringArray | Array of String, affected files or directories. |
| licenses | Array\[[License](#componentlicense)\] | Licenses. |
| Name | Type | Description |
| ------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
| id {: .kny-mono-font } | {{ kny:godot String }} | Identifier. |
| category {: .kny-mono-font } | {{ kny:godot String }} | Use to structure the licenses to top categories. E.g. Textures, Fonts, ... |
| name {: .kny-mono-font } | {{ kny:godot String }} | Name of the software or component. |
| version {: .kny-mono-font } | {{ kny:godot String }} | Version of the software or component. |
| copyright {: .kny-mono-font } | {{ kny:godot PackedStringArray }} | Copyrights. |
| contact {: .kny-mono-font } | {{ kny:godot String }} | Contact of developer. |
| description {: .kny-mono-font } | {{ kny:godot String }} | Additional description. |
| web {: .kny-mono-font } | {{ kny:godot String }} | Web url to project page. |
| paths {: .kny-mono-font } | {{ kny:godot PackedStringArray }} | Path to affected files or directories. |
| licenses {: .kny-mono-font } | {{ kny:godot Array }}\[[License](#componentlicense)\] | Licenses. |

#### Methods

`get_warnings() -> PackedStringArray`
{{ kny:godot PackedStringArray }} get_warnings () const {: .kny-mono-font }
: Get warnings regarding this component, e.g. missing license.

`serialize() -> Dictionary`
{{ kny:godot Dictionary }} serialize () const {: .kny-mono-font }
: Serialize to dictionary.

`deserialize(data: Dictionary) -> Component`
[Component](#component) deserialize ( {{ kny:godot Dictionary }} data ) {: .kny-mono-font }
: Load values from dictionary.

`duplicate() -> Component`
[Component](#component) duplicate () const {: .kny-mono-font }
: Returns a duplicate of itself.

### Component.License
Expand All @@ -108,26 +123,26 @@ License class.

#### Properties

| Name | Type | Description |
|------------|--------|-------------------------------------------------------------------------------------------|
| name | String | Full name. |
| identifier | String | Shortcode for this license. |
| text | String | License text. |
| file | String | License file. Will load the license text from this file automatically if `text` is empty. |
| web | String | Web present of the license. |
| Name | Type | Description |
| ------------------------------ | ---------------------- | ----------------------------------------------------------------------------------------- |
| name {: .kny-mono-font } | {{ kny:godot String }} | Full name. |
| identifier {: .kny-mono-font } | {{ kny:godot String }} | Shortcode for this license. |
| text {: .kny-mono-font } | {{ kny:godot String }} | License text. |
| file {: .kny-mono-font } | {{ kny:godot String }} | License file. Will load the license text from this file automatically if `text` is empty. |
| web {: .kny-mono-font } | {{ kny:godot String }} | Web present of the license. |

#### Methods

`get_license_text() -> String`
{{ kny:godot String }} get_license_text () const {: .kny-mono-font }
: Either returns the license text or loads the text from file or a message that the text could not be loaded.

`serialize() -> Dictionary`
{{ kny:godot String }} serialize () const {: .kny-mono-font }
: Serialize to dictionary.

`deserialize() -> Dictionary`
[License](#componentlicense) deserialize ( {{ kny:godot Dictionary }} data ) {: .kny-mono-font }
: Load values from dictionary.

`duplicate() -> License`
[License](#componentlicense) duplicate () const {: .kny-mono-font }
: Returns a duplicate of itself.

## Changelog
Expand Down
Loading

0 comments on commit 24a39ff

Please sign in to comment.