Skip to content

Commit 1ff6f01

Browse files
merksmerks
committed
Improve and fix the markdown documentation
- Add a .project file to `docs` folder for a project named `org.eclipse.platform.docs` - Remove internal table of content entries. - Fix broken links and avoid absolute raw and self links.
1 parent d1de5d9 commit 1ff6f01

35 files changed

+76
-446
lines changed

‎docs/.project

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<projectDescription>
3+
<name>org.eclipse.platform.docs</name>
4+
<comment></comment>
5+
<projects>
6+
</projects>
7+
<buildSpec>
8+
</buildSpec>
9+
<natures>
10+
</natures>
11+
</projectDescription>

‎docs/.settings/org.eclipse.core.resources.prefs

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
eclipse.preferences.version=1
2+
encoding/<project>=UTF-8

‎docs/API_Central.md

+10-10
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,15 @@ This page is a hub to collect information about Eclipse Project APIs.
66
### API Guidelines
77

88
* [How to use the Eclipse API](http://www.eclipse.org/articles/Article-API-Use/index.html) Guidelines for using Eclipse APIs to ensure that your code will keep working as Eclipse evolves.
9-
* [Evolving Java-based APIs](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs.md) Guidelines for how to evolve Java-based APIs while maintaining compatibility with existing client code.
10-
* [Javadoc](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Javadoc.md) How to write Javadoc
11-
* [Provisional API Guidelines](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Provisional_API_Guidelines.md)
12-
* [API Removal Process](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/ApiRemovalProcess.md)
13-
* [Deprecation Policy](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Eclipse_API_Central_Deprecation_Policy.md)
14-
* [Policy on use of Export-Package](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Export-Package.md)
15-
* [Version Numbering](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/VersionNumbering.md) Guidelines on how to assign and evolve plug-in version numbers
16-
* [Naming Conventions](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Naming_Conventions.md) How to name things like packages, classes, and methods
17-
* [Code Conventions](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Coding_Conventions.md) How to make Java code readable
18-
* [Eclipse Doc Conventions](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Eclipse_Doc_Style_Guide.md) Guide how to write Eclipse docs
9+
* [Evolving Java-based APIs](Evolving-Java-based-APIs.md) Guidelines for how to evolve Java-based APIs while maintaining compatibility with existing client code.
10+
* [Javadoc](Javadoc.md) How to write Javadoc
11+
* [Provisional API Guidelines](Provisional_API_Guidelines.md)
12+
* [API Removal Process](ApiRemovalProcess.md)
13+
* [Deprecation Policy](Eclipse_API_Central_Deprecation_Policy.md)
14+
* [Policy on use of Export-Package](Export-Package.md)
15+
* [Version Numbering](VersionNumbering.md) Guidelines on how to assign and evolve plug-in version numbers
16+
* [Naming Conventions](Naming_Conventions.md) How to name things like packages, classes, and methods
17+
* [Code Conventions](Coding_Conventions.md) How to make Java code readable
18+
* [Eclipse Doc Conventions](Eclipse_Doc_Style_Guide.md) Guide how to write Eclipse docs
1919
* [User interface guidelines](https://github.com/eclipse-platform/ui-best-practices)
2020

‎docs/ApiRemovalProcess.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# API removal process
22

3-
See [Eclipse Project Deprecation Policy](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Eclipse_API_Central_Deprecation_Policy.md) for more information.
3+
See [Eclipse Project Deprecation Policy](Eclipse_API_Central_Deprecation_Policy.md) for more information.
44

55
For new API planned removals use:
66

‎docs/Coding_Conventions.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Modifiers should be ordered as specified in the JLS and summarized in [AST#newMo
2626
synchronized native strictfp transient volatile
2727

2828

29-
For Javadoc conventions, see Oracle's [How to Write Doc Comments for the Javadoc Tool](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html) and [Eclipse/API_Central](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/API_Central.md).
29+
For Javadoc conventions, see Oracle's [How to Write Doc Comments for the Javadoc Tool](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html) and [Eclipse/API_Central](API_Central.md).
3030

3131
For Eclipse projects, there is no policy that requires a specific coding format or style, though the Eclipse style in the formatter and cleanup is preferred. Project teams typically determine their own styles and then commit the appropriate files. One way is to commit files on a per-project basis, the other is to have a central set of files that should be imported by each committer. See [Eclipse Incubation Mailing List, 20-June-2016](https://dev.eclipse.org/mhonarc/lists/incubation/msg00141.html).
3232

‎docs/Eclipse_API_Central_Deprecation_Policy.md

+2-13
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,6 @@ Eclipse/API Central/Deprecation Policy
44
This page contains Eclipse Project guidelines on API deprecation.
55
This page is maintained by the [Eclipse/PMC](https://eclipse.dev/eclipse/team-leaders.php).
66

7-
Contents
8-
--------
9-
10-
* [1 What is Deprecation?](#What-is-Deprecation.3F)
11-
* [1.1 Process to deprecate an API](#Process-to-deprecate-an-API)
12-
* [2 Identifying Deprecated API](#Identifying-Deprecated-API)
13-
* [2.1 Java API](#Java-API)
14-
* [2.2 Extension Points](#Extension-Points)
15-
* [3 Removal of Deprecated API](#Removal-of-Deprecated-API)
16-
* [3.1 Third Party API](#Third-Party-API)
17-
187

198
What is Deprecation?
209
====================
@@ -32,7 +21,7 @@ Identifying Deprecated API
3221
==========================
3322

3423
This section describes how clients can identify what API is deprecated.
35-
To identify API from non-API, see [Provisional API Guidelines](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Provisional_API_Guidelines.md)
24+
To identify API from non-API, see [Provisional API Guidelines](Provisional_API_Guidelines.md)
3625

3726
Java API
3827
--------
@@ -54,7 +43,7 @@ Extension Points
5443
Elements and attributes in extension points are deprecated by setting the "Deprecated" property to true in the PDE extension point schema editor.
5544
The entire extension point can be deprecated by deprecating the "extension" element, which is the top level element at the root of any contribution to the extension point.
5645

57-
![Schema-deprecation.png](https://raw.githubusercontent.com/eclipse-platform/eclipse.platform/master/docs/images/Schema-deprecation.png)
46+
![Schema-deprecation.png](images/Schema-deprecation.png)
5847

5948
Removal of Deprecated API
6049
=========================

‎docs/Eclipse_Doc_Style_Guide.md

-11
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,6 @@ This document gives the style conventions to be used in [Eclipse help](/Eclipse_
55
The Eclipse help has the following topic types: Tutorial (Getting Started), Concept, Task, and Reference.
66
These topic types are based on the [Darwin Information Typing Architecture (DITA)](http://www.ibm.com/developerworks/library/x-dita1/) standards.
77

8-
Contents
9-
--------
10-
11-
* [1 Topic Titles](#Topic-Titles)
12-
* [2 Lists](#Lists)
13-
* [3 Inline Markup](#Inline-Markup)
14-
* [4 Topic Content](#Topic-Content)
15-
* [5 Tables](#Tables)
16-
* [6 CSS Class Summary](#CSS-Class-Summary)
17-
* [7 Graphics](#Graphics)
18-
* [8 Indexing](#Indexing)
198

209
### Topic Titles
2110

‎docs/Evolving-Java-based-APIs-2.md

+7-24
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,8 @@
11
Evolving Java-based APIs 2
22
==========================
33

4-
Part 2 of [Evolving\_Java-based\_APIs](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs.md).
5-
6-
Contents
7-
--------
8-
9-
* [1 Achieving API Binary Compatibility](#Achieving-API-Binary-Compatibility)
10-
* [1.1 Evolving API packages](#Evolving-API-packages)
11-
* [1.2 Evolving API Interfaces](#Evolving-API-Interfaces)
12-
* [1.2.1 Evolving API interfaces - API methods](#Evolving-API-interfaces---API-methods)
13-
* [1.2.2 Evolving API interfaces - API fields](#Evolving-API-interfaces---API-fields)
14-
* [1.2.3 Evolving API interfaces - API type members](#Evolving-API-interfaces---API-type-members)
15-
* [1.3 Evolving API Classes](#Evolving-API-Classes)
16-
* [1.3.1 Evolving API classes - API methods and constructors](#Evolving-API-classes---API-methods-and-constructors)
17-
* [1.3.2 Evolving API classes - API fields](#Evolving-API-classes---API-fields)
18-
* [1.3.3 Evolving API classes - API type members](#Evolving-API-classes---API-type-members)
19-
* [1.4 Evolving non-API packages](#Evolving-non-API-packages)
20-
* [1.5 Turning non-generic types and methods into generic ones](#Turning-non-generic-types-and-methods-into-generic-ones)
21-
* [1.6 Evolving annotations on API elements](#Evolving-annotations-on-API-elements)
22-
* [2 Other Notes](#Other-Notes)
4+
Part 2 of [Evolving\_Java-based\_APIs](Evolving-Java-based-APIs.md).
5+
236

247
Achieving API Binary Compatibility
258
----------------------------------
@@ -95,13 +78,13 @@ Evolving API interfaces is somewhat more straightforward than API classes since
9578
| Delete element from annotation type | - | **Breaks compatibility** (6) |
9679

9780
(0) Although adding a new method to an API interface which need not be reimplemented by Clients does not break binary compatibility, a pre-existing Client subclass of an existing implementation might still provide a pre-existing implementation of a method by this name.
98-
See [Evolving Java-based APIs#Example 4 - Adding an API method](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs.md#Achieving-API-Binary-Compatibility) in the preceding section for why this breaks API contract compatibility.
81+
See [Evolving Java-based APIs#Example 4 - Adding an API method](Evolving-Java-based-APIs.md#Achieving-API-Binary-Compatibility) in the preceding section for why this breaks API contract compatibility.
9982

10083
(1) Adding a new method to an API interface that is implemented by Clients (e.g., a callback, listener, or visitor interface) breaks compatibility because hypothetical pre-existing implementations do not implement the new method.
10184

10285
(2) Adding an API field to an API interface that is implemented by Clients is dangerous in two respects:
10386

104-
* It may break API contract compatibility similar to [Evolving\_Java-based\_APIs#Example\_4\_-\_Adding\_an\_API\_method](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs.md#Achieving-API-Binary-Compatibility) in case of name clashes.
87+
* It may break API contract compatibility similar to [Evolving\_Java-based\_APIs#Example\_4\_-\_Adding\_an\_API\_method](Evolving-Java-based-APIs.md#Achieving-API-Binary-Compatibility) in case of name clashes.
10588
* It may cause linkage errors in case an instance (respectively static) field hides a static (respectively instance) field, see [JLS8 13.4.8](https://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.4.8). This can not happen if all field declarations follow the usual naming conventions from [JLS8 6.1](https://docs.oracle.com/javase/specs/jls/se8/html/jls-6.html#jls-6.1) and classes only have API fields that are either
10689
* "static final" (and hence have a name that doesn't contain any lowercase letters), or
10790
* non-static and non-final (and hence have a name that contains a least one lowercase letter)
@@ -225,15 +208,15 @@ Evolving API classes is somewhat more complex than API interfaces due to the wid
225208
| Re-order enum constants | - | Binary compatible (8) |
226209

227210
(0) Although adding a new method to an API class which need not be reimplemented by Clients does not break binary compatibility, a pre-existing subclass might still provide a pre-existing implementation of a method by this name.
228-
See [Evolving Java-based APIs#Example 4 - Adding an API method](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs.md#Achieving-API-Binary-Compatibility) in the preceding section for why this breaks API contract compatibility.
211+
See [Evolving Java-based APIs#Example 4 - Adding an API method](Evolving-Java-based-APIs.md#Achieving-API-Binary-Compatibility) in the preceding section for why this breaks API contract compatibility.
229212

230213
(1) Adding a new method to an API class that must be reimplemented by Clients breaks compatibility because pre-existing subclasses would not provide any such implementation.
231214

232215
(2) Adding the first constructor to an API class causes the compiler to no longer generate a default (public, 0 argument) constructor, thereby breaking compatibility with pre-existing code that invoked this API constructor. To avoid this pitfall, API classes should always explicitly declare at least one constructor.
233216

234217
(3) Adding an API field to an API class that is extended by Clients is dangerous in two respects:
235218

236-
* It may break API contract compatibility similar to [Evolving\_Java-based\_APIs#Example\_4\_-\_Adding\_an\_API\_method](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs.md#Achieving-API-Binary-Compatibility) in case of name clashes.
219+
* It may break API contract compatibility similar to [Evolving\_Java-based\_APIs#Example\_4\_-\_Adding\_an\_API\_method](Evolving-Java-based-APIs.md#Achieving-API-Binary-Compatibility) in case of name clashes.
237220
* It may cause linkage errors in case an instance (respectively static) field hides a static (respectively instance) field, see [JLS8 13.4.8](https://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.4.8). This can not happen if all field declarations follow the usual naming conventions from [JLS8 6.1](https://docs.oracle.com/javase/specs/jls/se8/html/jls-6.html#jls-6.1) and classes only have API fields that are either
238221
* "static final" (and hence have a name that doesn't contain any lowercase letters), or
239222
* non-static and non-final (and hence have a name that contains a least one lowercase letter)
@@ -390,5 +373,5 @@ Parties that declare annotation types should try to provide helpful guidance for
390373
Other Notes
391374
-----------
392375

393-
See [Part 3](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs-3.md).
376+
See [Part 3](Evolving-Java-based-APIs-3.md).
394377

‎docs/Evolving-Java-based-APIs-3.md

+3-19
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,8 @@
11
Evolving Java-based APIs 3
22
==========================
33

4-
Part 3 of [Evolving\_Java-based\_APIs](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs.md).
5-
6-
Contents
7-
--------
8-
9-
* [1 Other notes](#Other-notes)
10-
* [1.1 Data Compatibility](#Data-Compatibility)
11-
* [1.2 Standard Workarounds](#Standard-Workarounds)
12-
* [1.2.1 Deprecate and Forward](#Deprecate-and-Forward)
13-
* [1.2.2 Start over in a New Package](#Start-over-in-a-New-Package)
14-
* [1.2.3 Adding an Argument](#Adding-an-Argument)
15-
* [1.2.4 "2" Convention](#.222.22-Convention)
16-
* [1.2.5 COM Style](#COM-Style)
17-
* [1.2.6 Making Obsolete Hook Methods Final](#Making-Obsolete-Hook-Methods-Final)
18-
* [1.3 Defective API Specifications](#Defective-API-Specifications)
19-
* [1.4 A Word about Source Code Incompatibilities](#A-Word-about-Source-Code-Incompatibilities)
20-
* [1.5 Java Reflection](#Java-Reflection)
21-
* [1.6 Versioning](#Versioning)
4+
Part 3 of [Evolving\_Java-based\_APIs](Evolving-Java-based-APIs.md).
5+
226

237
Other notes
248
===========
@@ -185,4 +169,4 @@ Versioning
185169
----------
186170

187171
It should be easy for API clients to know whether a new version of your components broke APIs or not.
188-
Eclipse projects implement semantic versioning according to the [Version Numbering](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/VersionNumbering.md) specification.
172+
Eclipse projects implement semantic versioning according to the [Version Numbering](VersionNumbering.md) specification.

‎docs/Evolving-Java-based-APIs.md

+5-19
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,13 @@ Evolving Java-based APIs
44
Document is currently split in 3 parts:
55

66
* Part 1: What is an API? (this page)
7-
* [Part 2: Achieving API Binary Compatibility](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs-2.md)
8-
* [Part 3: Other Notes](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs-3.md)
7+
* [Part 2: Achieving API Binary Compatibility](Evolving-Java-based-APIs-2.md)
8+
* [Part 3: Other Notes](Evolving-Java-based-APIs-3.md)
99

1010
This document is about how to evolve Java-based APIs while maintaining compatibility with existing client code.
1111
Without loss of generality, we'll assume that there is a generic **Component** with a **Component API**, with one party providing the Component and controlling its API.
1212
The other party, or parties, write **Client** code that use the Component's services through its API. This is a very typical arrangement.
1313

14-
Contents
15-
--------
16-
17-
* [1 API Java Elements](#API-Java-Elements)
18-
* [2 API Prime Directive](#API-Prime-Directive)
19-
* [3 Achieving API Contract Compatibility](#Achieving-API-Contract-Compatibility)
20-
* [3.1 Example 1 - Changing a method postcondition](#Example-1---Changing-a-method-postcondition)
21-
* [3.2 Example 2 - Changing a method precondition](#Example-2---Changing-a-method-precondition)
22-
* [3.3 Example 3 - Changing a field invariant](#Example-3---Changing-a-field-invariant)
23-
* [3.4 Example 4 - Adding an API method](#Example-4---Adding-an-API-method)
24-
* [3.5 General Rules for Contract Compatibility](#General-Rules-for-Contract-Compatibility)
25-
* [4 Achieving API Binary Compatibility](#Achieving-API-Binary-Compatibility)
26-
* [5 Other Notes](#Other-Notes)
27-
* [6 Bundle Versioning](#Bundle-Versioning)
2814

2915
API Java Elements
3016
-----------------
@@ -207,16 +193,16 @@ Whether a particular Component API change breaks or maintains contract compatibi
207193
Achieving API Binary Compatibility
208194
----------------------------------
209195

210-
See [Part 2](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs-2.md).
196+
See [Part 2](Evolving-Java-based-APIs-2.md).
211197

212198
Other Notes
213199
-----------
214200

215-
See [Part 3](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/Evolving-Java-based-APIs-3.md).
201+
See [Part 3](Evolving-Java-based-APIs-3.md).
216202

217203
Bundle Versioning
218204
-----------------
219205

220-
See [Version Numbering](https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/VersionNumbering.md)
206+
See [Version Numbering](VersionNumbering.md)
221207

222208

0 commit comments

Comments
 (0)