lib: improve synopsis and doc of many libs

Signed-off-by: Alexis Laferrière <alexis.laf@xymus.net>

diff --git a/lib/a_star.nit b/lib/a_star.nit
index 488181e..7b7ce02 100644 (file)
--- a/lib/a_star.nit
+++ b/lib/a_star.nit
@@ -14,9 +14,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Services related to pathfinding of graphs using A*
-# A single graph may have different properties according to the `PathContext` used
+# A* pathfinding in graphs
 #
+# A single graph may have different properties according to the `PathContext` used
 #
 # Usage:
 #

diff --git a/lib/android/README.md b/lib/android/README.md
index 47c0e4b..50ac38d 100644 (file)
--- a/lib/android/README.md
+++ b/lib/android/README.md
@@ -1,4 +1,4 @@
-The `android` module provides support for the Android platform
+Android platform support and APIs
 
 # Compilation for Android
 

diff --git a/lib/app/README.md b/lib/app/README.md
index 22f4f77..c5caa4b 100644 (file)
--- a/lib/app/README.md
+++ b/lib/app/README.md
@@ -1,4 +1,4 @@
-_app.nit_ is a framework to create cross-platform applications
+_app.nit_, a framework for portable applications
 
 The framework provides services to manage common needs of modern mobile applications:
 

diff --git a/lib/binary/binary.nit b/lib/binary/binary.nit
index 7e5c180..b6909cd 100644 (file)
--- a/lib/binary/binary.nit
+++ b/lib/binary/binary.nit
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Add reading and writing binary services
+# Read and write binary data with any `Reader` and `Writer`
 #
 # ~~~
 # var w = new FileWriter.open("/tmp/data.bin")

diff --git a/lib/bucketed_game.nit b/lib/bucketed_game.nit
index 4060dc4..b5542e4 100644 (file)
--- a/lib/bucketed_game.nit
+++ b/lib/bucketed_game.nit
@@ -14,12 +14,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Provides basic game logic utilities using buckets to coordinate and
-# optimize actions on game turn ends. Supports both action at each
-# end of turn as well as actions on some end of turns.
+# Game framework with an emphasis on efficient event coordination
 #
-# Allows for fast support of a large number of entities with rare actions,
-# such as a forest with many individual trees.
+# Provides basic game logic entities to manage a game where the logic is executed by turns:
+# `Game`, `GameTurn`, `GameEvent`, `Turnable`.
+# Also offers a bucket system to plan future events at a known number of turns in the future:
+# `Bucketable` and the services `act_next` and `act_in`.
+#
+# Efficiently support large number of entities with rare or sparse actions,
+# such as a forest with many individual trees growing slowly.
 module bucketed_game is serialize
 
 import serialization

diff --git a/lib/c.nit b/lib/c.nit
index a4a8e01..deb6765 100644 (file)
--- a/lib/c.nit
+++ b/lib/c.nit
@@ -14,8 +14,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Utilities and performant structure for the FFI with C
+# Structures and services for compatibility with the C language
 module c
+
 import core
 intrude import core::collection::array
 

diff --git a/lib/cocoa/cocoa.nit b/lib/cocoa/cocoa.nit
index 09e1291..3e20d87 100644 (file)
--- a/lib/cocoa/cocoa.nit
+++ b/lib/cocoa/cocoa.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# The Cocoa API is the development layer of OS X
+# Cocoa API, the development layer of OS X
 #
 # This module is only compatible with OS X.
 #

diff --git a/lib/cpp.nit b/lib/cpp.nit
index a2896d3..a09d634 100644 (file)
--- a/lib/cpp.nit
+++ b/lib/cpp.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Offers features to interface with C++ code and libraries
+# Services for compatibility with C++ code and libraries
 module cpp is
        new_annotation cppflags
 end

diff --git a/lib/curl/curl.nit b/lib/curl/curl.nit
index 11c39bf..f225a02 100644 (file)
--- a/lib/curl/curl.nit
+++ b/lib/curl/curl.nit
@@ -14,7 +14,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Curl services: `CurlHTTPRequest` and `CurlMail`
+# Data transfer with URL syntax
+#
+# Download or upload over HTTP with `CurlHTTPRequest` and send emails with `CurlMail`.
 module curl
 
 import native_curl

diff --git a/lib/egl.nit b/lib/egl.nit
index 781c2a4..8934b7e 100644 (file)
--- a/lib/egl.nit
+++ b/lib/egl.nit
@@ -14,8 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# EGL is an interface between the rendering APIs OpenGL, OpenGL ES, etc.
-# and the native windowing system.
+# Interface between rendering APIs (OpenGL, OpenGL ES, etc.) and the native windowing system.
 #
 # Most services of this module are a direct wrapper of the underlying
 # C library. If a method or class is not documented in Nit, refer to

diff --git a/lib/gtk/gtk.nit b/lib/gtk/gtk.nit
index 1d8ed48..405bb01 100644 (file)
--- a/lib/gtk/gtk.nit
+++ b/lib/gtk/gtk.nit
@@ -14,10 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Provides GTK+ widgets and functionalities
+# GTK+ widgets and services
 #
-# By default it provides services from GTK+ v3.4. You can get newer
-# features by importing submodules v3_6 or v3_8 with `import gtk::v3_6`.
+# By default provides services from GTK+ v3.4.
+# Newer features from v3.6 and v3.8 are available in the submodules v3_6 and v3_8 respectively.
 module gtk
 
 import v3_4

diff --git a/lib/ios/ios.nit b/lib/ios/ios.nit
index 9d5079d..98cb714 100644 (file)
--- a/lib/ios/ios.nit
+++ b/lib/ios/ios.nit
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# iOS services for Nit app on iOS
+# iOS platform support
 module ios
 
 import platform

diff --git a/lib/json/json.nit b/lib/json/json.nit
index b458d01..7df7e82 100644 (file)
--- a/lib/json/json.nit
+++ b/lib/json/json.nit
@@ -15,7 +15,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Provides two APIs to manipulate JSON strings.
+# Libraries to manipulate JSON strings.
 #
 # Both `dynamic` and `static` modules provide at least a method to parse a
 # value written in JSON, but only `static` provide a method to translate a

diff --git a/lib/jvm.nit b/lib/jvm.nit
index a9e8920..62cebe1 100644 (file)
--- a/lib/jvm.nit
+++ b/lib/jvm.nit
@@ -15,7 +15,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Manipulates the Java Virtual Machine
+# Java Virtual Machine services
 #
 # See: http://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/jniTOC.html
 module jvm is

diff --git a/lib/md5.nit b/lib/md5.nit
index 6495145..3fee2f8 100644 (file)
--- a/lib/md5.nit
+++ b/lib/md5.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Implements the md5 function in C
+# Native MD5 digest implementation as `Text::md5`
 module md5
 
 in "C Header" `{
@@ -489,7 +489,7 @@ in "C Header" `{
        }
 `}
 
-redef class String
+redef class Text
        # MD5 digest of `self`
        #
        # ~~~

diff --git a/lib/mpd.nit b/lib/mpd.nit
index e814b56..727ac60 100644 (file)
--- a/lib/mpd.nit
+++ b/lib/mpd.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Client for a MPD server
+# Music Player Daemon client library
 module mpd
 
 import socket

diff --git a/lib/noise.nit b/lib/noise.nit
index 9a1ecc0..ba09bc1 100644 (file)
--- a/lib/noise.nit
+++ b/lib/noise.nit
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Provides the noise generators `PerlinNoise` and `InterpolatedNoise`
+# Noise generators `PerlinNoise` and `InterpolatedNoise`
 module noise is serialize
 
 import serialization

diff --git a/lib/realtime.nit b/lib/realtime.nit
index ad64930..8cfa4da 100644 (file)
--- a/lib/realtime.nit
+++ b/lib/realtime.nit
@@ -10,7 +10,7 @@
 # You  are  allowed  to  redistribute it and sell it, alone or is a part of
 # another product.
 
-# Provides the Clock utility class to keep time of real time flow
+# Services to keep time of the wall clock time
 module realtime is ldflags "-lrt"
 
 in "C header" `{

diff --git a/lib/sdl.nit b/lib/sdl.nit
index 858e9b3..a8fa112 100644 (file)
--- a/lib/sdl.nit
+++ b/lib/sdl.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# SDL display support (used in Linux for windows and inputes only)
+# Simple DirectMedia Layer
 module sdl is
        cflags exec("sdl-config", "--cflags")
        ldflags(exec("sdl-config", "--libs"), "-lSDL_image -lSDL_ttf")

diff --git a/lib/signals.nit b/lib/signals.nit
index 6fd06d0..440fd39 100644 (file)
--- a/lib/signals.nit
+++ b/lib/signals.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Module to manage standard C signals
+# ANSI C signal handling
 #
 # Common usage imply 5 steps:
 #

diff --git a/lib/x11.nit b/lib/x11.nit
index 1ba2d13..bd5d82a 100644 (file)
--- a/lib/x11.nit
+++ b/lib/x11.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Serices from the X11 library
+# Services from the X11 library
 module x11 is pkgconfig
 
 `{
@@ -31,7 +31,7 @@ fun x_open_default_display: Pointer `{
 # Open a specific display
 #
 # `name` is in the format: "hostname:number.screen_number"
-# 
+#
 # See <http://www.x.org/releases/X11R7.7/doc/man/man3/XOpenDisplay.3.xhtml>
 fun x_open_display(name: String): Pointer import String.to_cstring `{
        return (void*)XOpenDisplay(String_to_cstring(name));