Skip to content

Commit 445caf1

Browse files
committed
Change monospace text formatting
Summary: Using `##` can cause some formatting issues, see D13071. Test Plan: See D13071. Reviewers: epriestley, #blessed_reviewers, chad Reviewed By: epriestley, #blessed_reviewers Subscribers: Korvin, epriestley Differential Revision: https://secure.phabricator.com/D13072
1 parent 447c372 commit 445caf1

36 files changed

+254
-255
lines changed

src/docs/contributor/adding_new_css_and_js.diviner

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,7 @@ To add a new CSS or JS file, create it in an appropriate location in
1818
`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phabricator/`
1919
directory.
2020

21-
Each file must ##@provides## itself as a component, declared in a header
22-
comment:
21+
Each file must `@provides` itself as a component, declared in a header comment:
2322

2423
LANG=css
2524
/**

src/docs/contributor/darkconsole.diviner

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ can use them to access different debugging and performance features.
3737
= Plugin: Error Log =
3838

3939
The "Error Log" plugin shows errors that occurred while generating the page,
40-
similar to the httpd ##error.log##. You can send information to the error log
40+
similar to the httpd `error.log`. You can send information to the error log
4141
explicitly with the @{function@libphutil:phlog} function.
4242

4343
If errors occurred, a red dot will appear on the plugin tab.

src/docs/contributor/javascript_coding_standards.diviner

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ guidelines, you can probably get away with skimming this document.
1818

1919
- Use two spaces for indentation. Don't use literal tab characters.
2020
- Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
21-
- Put a space after control keywords like ##if## and ##for##.
21+
- Put a space after control keywords like `if` and `for`.
2222
- Put a space after commas in argument lists.
23-
- Put space around operators like ##=##, ##<##, etc.
23+
- Put space around operators like `=`, `<`, etc.
2424
- Don't put spaces after function names.
2525
- Parentheses should hug their contents.
2626
- Generally, prefer to wrap code at 80 columns.
@@ -30,26 +30,26 @@ guidelines, you can probably get away with skimming this document.
3030
The Javascript language unambiguously dictates casing/naming rules; follow those
3131
rules.
3232

33-
- Name variables using ##lowercase_with_underscores##.
34-
- Name classes using ##UpperCamelCase##.
35-
- Name methods and properties using ##lowerCamelCase##.
36-
- Name global functions using ##lowerCamelCase##. Avoid defining global
33+
- Name variables using `lowercase_with_underscores`.
34+
- Name classes using `UpperCamelCase`.
35+
- Name methods and properties using `lowerCamelCase`.
36+
- Name global functions using `lowerCamelCase`. Avoid defining global
3737
functions.
38-
- Name constants using ##UPPERCASE##.
39-
- Write ##true##, ##false##, and ##null## in lowercase.
38+
- Name constants using `UPPERCASE`.
39+
- Write `true`, `false`, and `null` in lowercase.
4040
- "Internal" methods and properties should be prefixed with an underscore.
4141
For more information about what "internal" means, see
4242
**Leading Underscores**, below.
4343

4444
= Comments =
4545

46-
- Strongly prefer ##//## comments for making comments inside the bodies of
46+
- Strongly prefer `//` comments for making comments inside the bodies of
4747
functions and methods (this lets someone easily comment out a block of code
4848
while debugging later).
4949

5050
= Javascript Language =
5151

52-
- Use ##[]## and ##{}##, not ##new Array## and ##new Object##.
52+
- Use `[]` and `{}`, not `new Array` and `new Object`.
5353
- When creating an object literal, do not quote keys unless required.
5454

5555
= Examples =
@@ -66,7 +66,7 @@ rules.
6666
}
6767

6868
You should always put braces around the body of an if clause, even if it is only
69-
one line. Note that operators like ##>## and ##===## are also surrounded by
69+
one line. Note that operators like `>` and `===` are also surrounded by
7070
spaces.
7171

7272
**for (iteration):**
@@ -107,10 +107,10 @@ see @{article:Javascript Object and Array}.
107107
}
108108

109109
`break` statements should be indented to block level. If you don't push them
110-
in, you end up with an inconsistent rule for conditional ##break## statements,
111-
as in the ##2## case.
110+
in, you end up with an inconsistent rule for conditional `break` statements,
111+
as in the `2` case.
112112

113-
If you insist on having a "fall through" case that does not end with ##break##,
113+
If you insist on having a "fall through" case that does not end with `break`,
114114
make it clear in a comment that you wrote this intentionally. For instance:
115115

116116
lang=js

src/docs/contributor/n_plus_one.diviner

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@ The N+1 query problem is a common performance antipattern. It looks like this:
1414
// ...
1515
}
1616

17-
Assuming ##load_cats()## has an implementation that boils down to:
17+
Assuming `load_cats()` has an implementation that boils down to:
1818

1919
SELECT * FROM cat WHERE ...
2020

21-
..and ##load_hats_for_cat($cat)## has an implementation something like this:
21+
..and `load_hats_for_cat($cat)` has an implementation something like this:
2222

2323
SELECT * FROM hat WHERE catID = ...
2424

src/docs/contributor/phabricator_code_layout.diviner

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -20,21 +20,21 @@ most of its code in standardized subdirectories and classes.
2020

2121
= Best Practice Class and Subdirectory Organization =
2222

23-
Suppose you were working on the application ##Derp##.
23+
Suppose you were working on the application `Derp`.
2424

2525
phabricator/src/applications/derp/
2626

27-
If ##Derp## were as simple as possible, it would have one subdirectory:
27+
If `Derp` were as simple as possible, it would have one subdirectory:
2828

2929
phabricator/src/applications/derp/controller/
3030

31-
containing the file ##DerpController.php## with the class
31+
containing the file `DerpController.php` with the class
3232

33-
- ##DerpController##: minimally implements a ##processRequest()## method
33+
- `DerpController`: minimally implements a `processRequest()` method
3434
which returns some @{class:AphrontResponse} object. The class would probably
3535
extend @{class:PhabricatorController}.
3636

37-
If ##Derp## were (relatively) complex, one could reasonably expect to see
37+
If `Derp` were (relatively) complex, one could reasonably expect to see
3838
the following directory layout:
3939

4040
phabricator/src/applications/derp/conduit/
@@ -54,54 +54,54 @@ this document. See @{article:Adding New CSS and JS}.)
5454
phabricator/webroot/rsrc/js/application/derp/
5555
phabricator/webroot/rsrc/css/application/derp/
5656

57-
These directories under ##phabricator/src/applications/derp/## represent
57+
These directories under `phabricator/src/applications/derp/` represent
5858
the basic set of class types from which most Phabrictor applications are
59-
assembled. Each would contain a class file. For ##Derp##, these classes could be
59+
assembled. Each would contain a class file. For `Derp`, these classes could be
6060
something like:
6161

62-
- **DerpConstants**: constants used in the ##Derp## application.
62+
- **DerpConstants**: constants used in the `Derp` application.
6363
- **DerpController**: business logic providing functionality for a given
6464
URI. Typically, controllers load data via Storage or Query classes, then
6565
present the data to the user via one or more View classes.
6666
- **DerpEditor**: business logic for workflows that change one or more
6767
Storage objects. Editor classes are only necessary for particularly
6868
complicated edits and should be used pragmatically versus Storage objects.
69-
- **DerpException**: exceptions used in the ##Derp## application.
70-
- **DerpQuery**: query one or more storage objects for pertinent ##Derp##
69+
- **DerpException**: exceptions used in the `Derp` application.
70+
- **DerpQuery**: query one or more storage objects for pertinent `Derp`
7171
application data. @{class:PhabricatorOffsetPagedQuery} is particularly
7272
handy for pagination and works well with @{class:AphrontPagerView}.
7373
- **DerpReplyHandler**: business logic from any configured email interactions
74-
users can have with the ##Derp## application.
75-
- **DerpStorage**: storage objects for the ##Derp## application. Typically
74+
users can have with the `Derp` application.
75+
- **DerpStorage**: storage objects for the `Derp` application. Typically
7676
there is a base class which extends @{class:PhabricatorLiskDAO} to configure
7777
application-wide storage settings like the application (thus database) name.
7878
Reading more about the @{class:LiskDAO} is highly recommended.
79-
- **DerpView**: view objects for the ##Derp## application. Typically these
79+
- **DerpView**: view objects for the `Derp` application. Typically these
8080
extend @{class:AphrontView}.
81-
- **DerpConduitAPIMethod**: provides any and all ##Derp## application
81+
- **DerpConduitAPIMethod**: provides any and all `Derp` application
8282
functionality that is accessible over Conduit.
8383

84-
However, it is likely that ##Derp## is even more complex, and rather than
84+
However, it is likely that `Derp` is even more complex, and rather than
8585
containing one class, each directory has several classes. A typical example
8686
happens around the CRUD of an object:
8787

8888
- **DerpBaseController**: typically extends @{class:PhabricatorController},
89-
implements ##buildStandardPageResponse## with the ##Derp## application name
90-
and other ##Derp##-specific meta-data, and contains any controller-specific
91-
functionality used throughout the ##Derp## application.
92-
- **DerpDeleteController**: typically extends ##DerpBaseController## and
93-
presents a confirmation dialogue to the user about deleting a ##Derp##.
94-
- **DerpEditController**: typically extends ##DerpBaseController## and
95-
presents a form to create and edit ##Derps##. Most likely uses
96-
@{class:AphrontFormView} and various ##AphrontFormXControl## classes such as
89+
implements `buildStandardPageResponse` with the `Derp` application name
90+
and other `Derp`-specific meta-data, and contains any controller-specific
91+
functionality used throughout the `Derp` application.
92+
- **DerpDeleteController**: typically extends `DerpBaseController` and
93+
presents a confirmation dialogue to the user about deleting a `Derp`.
94+
- **DerpEditController**: typically extends `DerpBaseController` and
95+
presents a form to create and edit `Derps`. Most likely uses
96+
@{class:AphrontFormView} and various `AphrontFormXControl` classes such as
9797
@{class:AphrontFormTextControl} to create the form.
98-
- **DerpListController**: typically extends ##DerpBaseController## and displays
99-
a set of one or more ##Derps##. Might use @{class:AphrontTableView} to create
100-
a table of ##Derps##.
101-
- **DerpViewController**: typically extends ##DerpBaseController## and displays
102-
a single ##Derp##.
98+
- **DerpListController**: typically extends `DerpBaseController` and displays
99+
a set of one or more `Derps`. Might use @{class:AphrontTableView} to create
100+
a table of `Derps`.
101+
- **DerpViewController**: typically extends `DerpBaseController` and displays
102+
a single `Derp`.
103103

104-
Some especially awesome directories might have a ##__tests__## subdirectory
104+
Some especially awesome directories might have a `__tests__` subdirectory
105105
containing all pertinent unit test code for the class.
106106

107107
= Next Steps =

src/docs/contributor/php_coding_standards.diviner

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -19,21 +19,21 @@ guidelines, you probably don't need to read this super thoroughly.
1919

2020
- Use two spaces for indentation. Don't use tab literal characters.
2121
- Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
22-
- Put a space after control keywords like ##if## and ##for##.
22+
- Put a space after control keywords like `if` and `for`.
2323
- Put a space after commas in argument lists.
24-
- Put a space around operators like ##=##, ##<##, etc.
24+
- Put a space around operators like `=`, `<`, etc.
2525
- Don't put spaces after function names.
2626
- Parentheses should hug their contents.
2727
- Generally, prefer to wrap code at 80 columns.
2828

2929
= Case and Capitalization =
3030

31-
- Name variables and functions using ##lowercase_with_underscores##.
32-
- Name classes using ##UpperCamelCase##.
33-
- Name methods and properties using ##lowerCamelCase##.
31+
- Name variables and functions using `lowercase_with_underscores`.
32+
- Name classes using `UpperCamelCase`.
33+
- Name methods and properties using `lowerCamelCase`.
3434
- Use uppercase for common acronyms like ID and HTML.
35-
- Name constants using ##UPPERCASE##.
36-
- Write ##true##, ##false## and ##null## in lowercase.
35+
- Name constants using `UPPERCASE`.
36+
- Write `true`, `false` and `null` in lowercase.
3737

3838
= Comments =
3939

@@ -43,9 +43,9 @@ guidelines, you probably don't need to read this super thoroughly.
4343
= PHP Language Style =
4444

4545
- Use "<?php", not the "<?" short form. Omit the closing "?>" tag.
46-
- Prefer casts like ##(string)## to casting functions like ##strval()##.
47-
- Prefer type checks like ##$v === null## to type functions like
48-
##is_null()##.
46+
- Prefer casts like `(string)` to casting functions like `strval()`.
47+
- Prefer type checks like `$v === null` to type functions like
48+
`is_null()`.
4949
- Avoid all crazy alternate forms of language constructs like "endwhile"
5050
and "<>".
5151
- Always put braces around conditional and loop blocks.

src/docs/contributor/unit_tests.diviner

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ libphutil, Arcanist and Phabricator provide and use a simple unit test
99
framework. This document is aimed at project contributors and describes how to
1010
use it to add and run tests in these projects or other libphutil libraries.
1111

12-
In the general case, you can integrate ##arc## with a custom unit test engine
12+
In the general case, you can integrate `arc` with a custom unit test engine
1313
(like PHPUnit or any other unit testing library) to run tests in other projects.
1414
See @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
1515
for information on customizing engines.
@@ -18,20 +18,20 @@ for information on customizing engines.
1818

1919
To add new tests to a libphutil, Arcanist or Phabricator module:
2020

21-
- Create a ##__tests__/## directory in the module if it doesn't exist yet.
22-
- Add classes to the ##__tests__/## directory which extend from
21+
- Create a `__tests__/` directory in the module if it doesn't exist yet.
22+
- Add classes to the `__tests__/` directory which extend from
2323
@{class:PhabricatorTestCase} (in Phabricator) or
2424
@{class@arcanist:PhutilTestCase} (elsewhere).
25-
- Run ##arc liberate## on the library root so your classes are loadable.
25+
- Run `arc liberate` on the library root so your classes are loadable.
2626

2727
= Running Tests =
2828

2929
Once you've added test classes, you can run them with:
3030

31-
- ##arc unit path/to/module/##, to explicitly run module tests.
32-
- ##arc unit##, to run tests for all modules affected by changes in the
31+
- `arc unit path/to/module/`, to explicitly run module tests.
32+
- `arc unit`, to run tests for all modules affected by changes in the
3333
working copy.
34-
- ##arc diff## will also run ##arc unit## for you.
34+
- `arc diff` will also run `arc unit` for you.
3535

3636
= Example Test Case =
3737

@@ -76,11 +76,11 @@ in a number of ways. From best to worst:
7676
is reasonable.
7777
- Build a real database simulation layer (fairly complex).
7878
- Disable isolation for a single test by using
79-
##LiskDAO::endIsolateAllLiskEffectsToCurrentProcess();## before your test
80-
and ##LiskDAO::beginIsolateAllLiskEffectsToCurrentProcess();## after your
79+
`LiskDAO::endIsolateAllLiskEffectsToCurrentProcess();` before your test
80+
and `LiskDAO::beginIsolateAllLiskEffectsToCurrentProcess();` after your
8181
test. This will disable isolation for one test. NOT RECOMMENDED.
8282
- Disable isolation for your entire test case by overriding
83-
##getPhabricatorTestCaseConfiguration()## and providing
84-
##self::PHABRICATOR_TESTCONFIG_ISOLATE_LISK => false## in the configuration
83+
`getPhabricatorTestCaseConfiguration()` and providing
84+
`self::PHABRICATOR_TESTCONFIG_ISOLATE_LISK => false` in the configuration
8585
dictionary you return. This will disable isolation entirely. STRONGLY NOT
8686
RECOMMENDED.

src/docs/contributor/using_oauthserver.diviner

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ https://phabricator.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4
105105

106106
If the token has expired or is otherwise invalid, the client will receive
107107
an error indicating as such. In these cases, the client should re-initiate
108-
the entire ##Authorization Code Grant## flow.
108+
the entire `Authorization Code Grant` flow.
109109

110110
NOTE: See "Scopes" section below for more information on what data is
111111
currently exposed through the OAuth Server.

src/docs/flavor/javascript_object_array.diviner

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ behavior.
88
= Primitives =
99

1010
Javascript has two native datatype primitives, Object and Array. Both are
11-
classes, so you can use ##new## to instantiate new objects and arrays:
11+
classes, so you can use `new` to instantiate new objects and arrays:
1212

1313
COUNTEREXAMPLE
1414
var a = new Array(); // Not preferred.
@@ -42,7 +42,7 @@ and Array are both classes, but "object" is also a primitive type. Object is
4242

4343
= Objects are Maps, Arrays are Lists =
4444

45-
PHP has a single ##array## datatype which behaves like as both map and a list,
45+
PHP has a single `array` datatype which behaves like as both map and a list,
4646
and a common mistake is to treat Javascript arrays (or objects) in the same way.
4747
**Don't do this.** It sort of works until it doesn't. Instead, learn how
4848
Javascript's native datatypes work and use them properly.
@@ -94,9 +94,9 @@ Iterate over a list like this:
9494

9595
NOTE: There's some sparse array nonsense being omitted here, see below.
9696

97-
If you try to use ##for (var k in ...)## syntax to iterate over an Array, you'll
97+
If you try to use `for (var k in ...)` syntax to iterate over an Array, you'll
9898
pick up a whole pile of keys you didn't intend to and it won't work. If you try
99-
to use ##for (var ii = 0; ...)## syntax to iterate over an Object, it won't work
99+
to use `for (var ii = 0; ...)` syntax to iterate over an Object, it won't work
100100
at all.
101101

102102
If you consistently treat Arrays as lists and Objects as maps and use the
@@ -106,7 +106,7 @@ way.
106106
= hasOwnProperty() =
107107

108108
An issue with this model is that if you write stuff to Object.prototype, it will
109-
show up every time you use enumeration ##for##:
109+
show up every time you use enumeration `for`:
110110

111111
COUNTEREXAMPLE
112112
var o = {};
@@ -117,7 +117,7 @@ show up every time you use enumeration ##for##:
117117

118118
There are two ways to avoid this:
119119

120-
- test that ##k## exists on ##o## by calling ##o.hasOwnProperty(k)## in every
120+
- test that `k` exists on `o` by calling `o.hasOwnProperty(k)` in every
121121
single loop everywhere in your program and only use libraries which also do
122122
this and never forget to do it ever; or
123123
- don't write to Object.prototype.

src/docs/flavor/javascript_pitfalls.diviner

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,20 +27,20 @@ insert semicolons after each statement. You should also prefer to break lines in
2727
places where insertion of a semicolon would not make the unparseable parseable,
2828
usually after operators.
2929

30-
= ##with## is Bad News =
30+
= `with` is Bad News =
3131

3232
`with` is a pretty bad feature, for this reason among others:
3333

3434
with (object) {
3535
property = 3; // Might be on object, might be on window: who knows.
3636
}
3737

38-
Avoid ##with##.
38+
Avoid `with`.
3939

40-
= ##arguments## is not an Array =
40+
= `arguments` is not an Array =
4141

42-
You can convert ##arguments## to an array using JX.$A() or similar. Note that
43-
you can pass ##arguments## to Function.prototype.apply() without converting it.
42+
You can convert `arguments` to an array using JX.$A() or similar. Note that
43+
you can pass `arguments` to Function.prototype.apply() without converting it.
4444

4545
= Object, Array, and iteration are needlessly hard =
4646

@@ -82,6 +82,6 @@ objects and can have methods and properties, and inherit from Array.prototype,
8282
Number.prototype, etc.) and their logical behavior is at best absurd and at
8383
worst strictly wrong.
8484

85-
**Never use** ##new Number()##, ##new String()## or ##new Boolean()## unless
85+
**Never use** `new Number()`, `new String()` or `new Boolean()` unless
8686
your Javascript is God Tier and you are absolutely sure you know what you are
8787
doing.

0 commit comments

Comments
 (0)