| <?xml version="1.0" encoding="ISO-8859-1" ?> | |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
| <html xmlns="http://www.w3.org/1999/xhtml"> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> | |
| <title>How to spot an API</title> | |
| </head> | |
| <body> | |
| <dl> | |
| <dt>Declared API</dt><dd>means an API declared as such, either in | |
| a component.xml file, or by virtue of having a "@since" tag in the | |
| JavaDoc. Technically, an API should be both in the component.xml file, | |
| and have a @since tag, but if only one of those conditions is true, | |
| we assume the omission is the error.</dd> | |
| <dt>Provisional API</dt><dd>means a non-API that was documented | |
| as, basically, "we'd like this to be API someday, but have not had the | |
| time or resources or experience to officially declare it as such". The | |
| significance being, that anyone who uses it is accepting the risk of having to | |
| adjust to future changes (whereas APIs never change).</dd> | |
| <dt>Internal non-API</dt><dd>is the case where some adopter has used some | |
| class clearly designated as "internal". While we still will use care to not | |
| capriciously break adopters who do that, its less clear we could accommodate, but we will work to figure out why | |
| they were, if there is a better way, etc.</dd> | |
| </dl> | |
| </body> | |
| </html> |