Skip to contentSkip to conversation

doc: Add very simple library API writing guidelines docs

PATCH New Petr Vorel 2 participants 4 messages Sep 24, 2019 – Feb 21, 2020

lore
Share & tools
lore

Petr Vorel

author
#0 lore raw

PATCH 1/1 doc: Add very simple library API writing guidelines docs

---
Hi,

this is rather kind of a bad joke than a serious patch.

Inspired by Christian patch, where he adds write-tests-for-shell-lib.txt. I guess we need more high level docs, where content of his patch would be added.

Feel free to write more useful docs than my stub.

Kind regards,
Petr

[1] https://patchwork.ozlabs.org/patch/1151766/

 doc/library-api-writing-guidelines.txt | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 doc/library-api-writing-guidelines.txt
doc/library-api-writing-guidelines.txt new file +25 -0
new file mode 100644
index 000000000..a238ee046
@@ -0,0 +1,25 @@
+LTP Library API Writing Guidelines
+==================================
+
+1. General Rules
+----------------
+
+For extending library API it applies the same general rules as for writing tests
+(see test-writing-guidelines.txt), with strong focus on readability and simplicity.
+
+Library tests are in lib/newlib_tests directory.
+
+2. C API
+--------
+
+API source code is in headers include/*.h, include/lapi/*.h (backward compatibility)
+and C sources in lib/*.c. Files have tst_ prefix.
+
+3. Shell API
+------------
+
+API source code is in tst_test.sh, tst_security.sh and tst_net.sh
+(all in testcases/lib directory).
+
+Changes in the shell API should not introduce uncommon dependencies
+(use basic commands installed everywhere by default).
Signature · 1 line
2.22.1
#1 lore raw

PATCH 1/1 doc: Add very simple library API writing guidelines docs

Hi!

Quoted 1 line

Feel free to write more useful docs than my stub.

It's a good stub actually, there is a lot that is not described at all.

We should probably draft a longer readme that describes why we also have a mechanism for additional libraries in place and when to use it. Generally we lack a lot of documentation.

Now we only need someone to volunteer to write it down.

Quoted 40 lines

[1] https://patchwork.ozlabs.org/patch/1151766/

 doc/library-api-writing-guidelines.txt | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 doc/library-api-writing-guidelines.txt
doc/library-api-writing-guidelines.txt new file +25 -0
new file mode 100644
index 000000000..a238ee046
@@ -0,0 +1,25 @@
+LTP Library API Writing Guidelines
+==================================
+
+1. General Rules
+----------------
+
+For extending library API it applies the same general rules as for writing tests
+(see test-writing-guidelines.txt), with strong focus on readability and simplicity.
+
+Library tests are in lib/newlib_tests directory.
+
+2. C API
+--------
+
+API source code is in headers include/*.h, include/lapi/*.h (backward compatibility)
+and C sources in lib/*.c. Files have tst_ prefix.
+
+3. Shell API
+------------
+
+API source code is in tst_test.sh, tst_security.sh and tst_net.sh
+(all in testcases/lib directory).
+
+Changes in the shell API should not introduce uncommon dependencies
+(use basic commands installed everywhere by default).
Signature · 1 line
2.22.1
Signature · 2 lines
Cyril Hrubis
[email protected]
author
#2 lore raw

PATCH 1/1 doc: Add very simple library API writing guidelines docs

Hi Cyril,

Quoted 6 lines
Quoted 1 line

Feel free to write more useful docs than my stub.

It's a good stub actually, there is a lot that is not described at all.

We should probably draft a longer readme that describes why we also have a mechanism for additional libraries in place and when to use it.

"additional libraries" do you mean tst_net.sh or what? Or a text "put useful things into library"? Or "try to keep synced shell and C API?

Quoted 1 line

Generally we lack a lot of documentation.

Yep.

Quoted 1 line

Now we only need someone to volunteer to write it down.

:).

Kind regards,
Petr