| <?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> |
