Browse Source

More work on docs

master
Chris Smith 5 months ago
parent
commit
54e2922e3d
1 changed files with 101 additions and 19 deletions
  1. 101
    19
      docs/index.adoc

+ 101
- 19
docs/index.adoc View File

@@ -37,15 +37,6 @@ repository and then the KtIrc dependency; you may already be using
37 37
 JCenter for other dependencies -- in that case just skip the
38 38
 repository configuration!
39 39
 
40
-[TIP]
41
-====
42
-KtIrc adheres to semantic versioning: you can expect to upgrade between
43
-minor versions without problems (e.g. from `0.1.2` to `0.13.7`); major
44
-version changes may include breaking changes such as the removal of
45
-deprecated methods. You should check the changelog before updating to
46
-a new major version.
47
-====
48
-
49 40
 .Gradle (using Kotlin DSL)
50 41
 [source,kotlin,subs="attributes"]
51 42
 ----
@@ -196,6 +187,30 @@ may need to process. At minimum, when receiving a BatchReceived
196 187
 event you should apply your normal processing to all the events
197 188
 contained within.
198 189
 
190
+=== Versioning and deprecation
191
+
192
+As of version 1.0.0, KtIrc adheres to semantic versioning: you can
193
+expect to upgrade between minor versions without problems (e.g. from `1.1.2`
194
+to `1.13.7`); major version changes include breaking changes such as the
195
+removal of methods. You should check the changelog before updating to
196
+a new major version.
197
+
198
+Where at all possible, methods will be deprecated for a full major version
199
+cycle before being removed. e.g., a method deprecated in `0.5.0` will be
200
+present in all `1.x.x` releases and will likely be removed fully in `2.0.0`.
201
+This gives users of the library opportunity to migrate away from deprecated
202
+methods in advance of their removal.
203
+
204
+In KtIrc, we define a breaking change as one that either:
205
+
206
+* removes public methods, classes, or fields; or
207
+* adds required parameters to an existing public method; or
208
+* significantly alters the default behaviour without any API changes
209
+
210
+Note that changes that don't meet this threshold to be classed as "breaking"
211
+may still cause errors in downstream projects. In particular, new enum
212
+values may be added which could cause compilation errors if they are
213
+used exhaustively (e.g. in a `return when` construct with no `else` clause).
199 214
 
200 215
 == IrcClient DSL
201 216
 
@@ -1006,25 +1021,89 @@ handle the ChannelAway events, and vice-versa.
1006 1021
 
1007 1022
 === Channel/User events
1008 1023
 
1009
-TODO
1024
+These are events that may be targeted to either a channel or a user. You
1025
+can use the <<IsChannel>> method to determine whether the target of one
1026
+of these events is a channel or not.
1010 1027
 
1011 1028
 ==== MessageReceived
1029
+* Type: IrcEvent, TargetedEvent, SourcedEvent
1030
+* Properties:
1031
+** `user`: `User` - the user who sent the message
1032
+** `target`: `String` - the channel or user the message was sent to
1033
+** `message`: `String` - the text of the message
1012 1034
 
1013
-TODO
1035
+Raised whenever we receive a message on a channel or directly to our
1036
+local user. CTCPs and Actions, which are client-side extensions to
1037
+messages will not raise this event; instead they will raise
1038
+<<CtcpReceived>> and <<ActionReceived>> respectively.
1039
+
1040
+The <<Reply>> function can be used to reply to a message,
1041
+automatically selecting the appropriate target and including the
1042
+message ID in the reply where supported by the IRC server.
1014 1043
 
1015 1044
 ==== NoticeReceived
1045
+* Type: IrcEvent, TargetedEvent, SourcedEvent
1046
+* Properties:
1047
+** `user`: `User` - the user who sent the notice
1048
+** `target`: `String` - the channel or user the notice was sent to
1049
+** `message`: `String` - the text of the notice
1016 1050
 
1017
-TODO
1051
+Raised whenever we receive a notice on a channel or directly to our
1052
+local user. CTCP replies, which are client-side extensions to
1053
+notices will not raise this event; instead they will raise
1054
+<<CtcpReplyReceived>>.
1055
+
1056
+During connection, notices may be received which target either the
1057
+magic string `AUTH` or `*`, as the client's nickname is not yet
1058
+known.
1018 1059
 
1019 1060
 ==== ActionReceived
1061
+* Type: IrcEvent, TargetedEvent, SourcedEvent
1062
+* Properties:
1063
+** `user`: `User` - the user who sent the action
1064
+** `target`: `String` - the channel or user the action was sent to
1065
+** `action`: `String` - the text of the action
1020 1066
 
1021
-TODO
1067
+Raised whenever we receive an 'action' message on a channel or
1068
+directly to our local user. Actions are a client-side extension
1069
+to the IRC protocol that allow users to describe something they
1070
+are doing.
1022 1071
 
1023 1072
 ==== CtcpReceived
1073
+* Type: IrcEvent, TargetedEvent, SourcedEvent
1074
+* Properties:
1075
+** `user`: `User` - the user who sent the CTCP
1076
+** `target`: `String` - the channel or user the CTCP was sent to
1077
+** `type`: `String` - the type of the CTCP
1078
+** `content`: `String` - the (possibly empty) content of the CTCP
1024 1079
 
1025
-TODO
1080
+Raised in response to a message that contains a CTCP
1081
+(client-to-client protocol) message other than an action.
1082
+CTCPs have a type, such as `PING`, `VERSION`, and optionally
1083
+some content such as a timestamp or nonce when requesting a PING.
1084
+
1085
+KtIrc does not reply to any CTCPs by itself. Replies to CTCPs are
1086
+by convention sent to the originating user, even if the CTCP is
1087
+sent to a channel.
1026 1088
 
1027 1089
 ==== CtcpReplyReceived
1090
+* Type: IrcEvent, TargetedEvent, SourcedEvent
1091
+* Properties:
1092
+** `user`: `User` - the user who sent the CTCP reply
1093
+** `target`: `String` - the channel or user the reply was sent to
1094
+** `type`: `String` - the type of the CTCP reply
1095
+** `content`: `String` - the (possibly empty) content of the CTCP reply
1096
+
1097
+Raised in response to a notice that contains a CTCP
1098
+(client-to-client protocol) reply. This usually occurs after we
1099
+have issued a CTCP request to a user or channel, and the `content`
1100
+argument will contain the remote client's response.
1101
+
1102
+Replies to CTCPs are by convention sent to the originating user,
1103
+even if the CTCP is sent to a channel. The `target` parameter
1104
+should therefore be the local user in most cases.
1105
+
1106
+=== User events
1028 1107
 
1029 1108
 TODO
1030 1109
 
@@ -1042,6 +1121,10 @@ for our own user.
1042 1121
 If the user is away but we don't know the reason for it, the `message`
1043 1122
 property will be empty.
1044 1123
 
1124
+==== ModeChanged
1125
+
1126
+TODO
1127
+
1045 1128
 ==== UserQuit
1046 1129
 
1047 1130
 TODO
@@ -1058,11 +1141,6 @@ TODO
1058 1141
 
1059 1142
 TODO
1060 1143
 
1061
-==== ModeChanged
1062
-
1063
-TODO
1064
-
1065
-
1066 1144
 === Other events
1067 1145
 
1068 1146
 ==== PingReceived
@@ -1165,6 +1243,10 @@ TODO
1165 1243
 
1166 1244
 TODO
1167 1245
 
1246
+=== IsChannel
1247
+
1248
+TODO
1249
+
1168 1250
 === IsLocalClient
1169 1251
 
1170 1252
 TODO

Loading…
Cancel
Save