New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: improved plugins.md #2237

Open
wants to merge 5 commits into
base: master
from

Conversation

Projects
None yet
3 participants
@Piankero
Contributor

Piankero commented Sep 13, 2018

As proposed in #2235 I added documentation for clarifying external tool integration.

@Piankero Piankero requested a review from sanssecours Sep 13, 2018

@markus2330

Thank you for improving the docu!

Is this also documented in src/plugins/doc?

Show outdated Hide outdated doc/tutorials/plugins.md
Show outdated Hide outdated doc/tutorials/plugins.md
Show outdated Hide outdated doc/tutorials/plugins.md
@sanssecours

I do not think I am the right person to review this. Maybe it would make more sense for @tom-wa or @markus2330 to have a look at this PR.

Show outdated Hide outdated doc/tutorials/plugins.md
Show outdated Hide outdated doc/tutorials/plugins.md
@Piankero

This comment has been minimized.

Show comment
Hide comment
@Piankero

Piankero Sep 13, 2018

Contributor

Is this also documented in src/plugins/doc?

Actually this documentation is empty and just links to the latest one.

Contributor

Piankero commented Sep 13, 2018

Is this also documented in src/plugins/doc?

Actually this documentation is empty and just links to the latest one.

@markus2330

This comment has been minimized.

Show comment
Hide comment
@markus2330

markus2330 Sep 14, 2018

Contributor

Actually this documentation is empty and just links to the latest one.

I do not understand. What do you mean by https://master.libelektra.org/src/plugins/doc is empty?

Contributor

markus2330 commented Sep 14, 2018

Actually this documentation is empty and just links to the latest one.

I do not understand. What do you mean by https://master.libelektra.org/src/plugins/doc is empty?

@Piankero

This comment has been minimized.

Show comment
Hide comment
@Piankero

Piankero Sep 17, 2018

Contributor

I mean that this file is basically empty and does simply link to the new docu.

Contributor

Piankero commented Sep 17, 2018

I mean that this file is basically empty and does simply link to the new docu.

@markus2330

This comment has been minimized.

Show comment
Hide comment
@markus2330

markus2330 Sep 21, 2018

Contributor

Yes, the preconditions should be in src/plugins/doc/doc.h, not in the README.md file.

Contributor

markus2330 commented Sep 21, 2018

Yes, the preconditions should be in src/plugins/doc/doc.h, not in the README.md file.

Piankero added some commits Oct 13, 2018

@markus2330

Still many problems in the docu.

@@ -216,6 +216,7 @@ you up to date with the multi-language support provided by Elektra.
## Documentation
- We fixed some minor spelling mistakes in the documentation. *(René Schwaiger)*
- Improved the plugins documentation. *(Michael Zronek)*

This comment has been minimized.

@markus2330

markus2330 Oct 14, 2018

Contributor

Very short info, what was your improvement about?

@markus2330

markus2330 Oct 14, 2018

Contributor

Very short info, what was your improvement about?

@@ -363,7 +363,10 @@ be called and the mounted file will be updated.
We haven't discussed `ELEKTRA_SET_ERROR` yet. Because Elektra is a library, printing errors to stderr wouldn't be a good idea. Instead, errors
and warnings can be appended to a key in the form of metadata. This is what `ELEKTRA_SET_ERROR` does. Because the parentKey always exists
even if a critical error occurs, we append the error to the `parentKey`. The first parameter is an id specifying the general error that occurred.
even if a critical error occurs, we write the error to the parentKey. The error does not necessarily have to be in a configuration.

This comment has been minimized.

@markus2330

markus2330 Oct 14, 2018

Contributor

What does the second sentence mean?

@markus2330

markus2330 Oct 14, 2018

Contributor

What does the second sentence mean?

@@ -363,7 +363,10 @@ be called and the mounted file will be updated.
We haven't discussed `ELEKTRA_SET_ERROR` yet. Because Elektra is a library, printing errors to stderr wouldn't be a good idea. Instead, errors
and warnings can be appended to a key in the form of metadata. This is what `ELEKTRA_SET_ERROR` does. Because the parentKey always exists
even if a critical error occurs, we append the error to the `parentKey`. The first parameter is an id specifying the general error that occurred.
even if a critical error occurs, we write the error to the parentKey. The error does not necessarily have to be in a configuration.
If there are multiple errors in a configuration, only the first occurrence will be written to the metadata of the `parentKey`.

This comment has been minimized.

@markus2330

markus2330 Oct 14, 2018

Contributor

Why now suddenly only in a configuration?

@markus2330

markus2330 Oct 14, 2018

Contributor

Why now suddenly only in a configuration?

even if a critical error occurs, we write the error to the parentKey. The error does not necessarily have to be in a configuration.
If there are multiple errors in a configuration, only the first occurrence will be written to the metadata of the `parentKey`.
The first parameter of `ELEKTRA_SET_ERROR` is an id specifying the general error that occurred.

This comment has been minimized.

@markus2330

markus2330 Oct 14, 2018

Contributor

an ID

@markus2330

markus2330 Oct 14, 2018

Contributor

an ID

Some applications want to call Elektra methods directly via native access.
A `KeySet` is a data structure over which functions can iterate. If you want to start again from to first element,
you have to explicitly call `rewind()` to set the internal pointer to the start.

This comment has been minimized.

@markus2330

markus2330 Oct 14, 2018

Contributor

ksRewind (ideally with link)

@markus2330

markus2330 Oct 14, 2018

Contributor

ksRewind (ideally with link)

## Note on Direct Method Calls via External Integrations
Some applications want to call Elektra methods directly via native access.

This comment has been minimized.

@markus2330

markus2330 Oct 14, 2018

Contributor

"Elektra methods" -> "functions exported by Elektra's plugin" otherwise the problem you describe will not occur.

@markus2330

markus2330 Oct 14, 2018

Contributor

"Elektra methods" -> "functions exported by Elektra's plugin" otherwise the problem you describe will not occur.

@@ -114,7 +114,8 @@
/**
* @brief Sets the error in the keys metadata.
*
* Include kdberrors.h to make it work:
* Include kdberrors.h to make it work.
* Only a single error can be written to the key.

This comment has been minimized.

@markus2330

markus2330 Oct 14, 2018

Contributor

Behavior not described. What happens if multiple calls are done.

@markus2330

markus2330 Oct 14, 2018

Contributor

Behavior not described. What happens if multiple calls are done.

@@ -114,7 +114,8 @@
/**
* @brief Sets the error in the keys metadata.
*
* Include kdberrors.h to make it work:
* Include kdberrors.h to make it work.

This comment has been minimized.

@markus2330

markus2330 Oct 14, 2018

Contributor

The : is needed because of the example (snippet) afterwards.

@markus2330

markus2330 Oct 14, 2018

Contributor

The : is needed because of the example (snippet) afterwards.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment