Qrhunter58

This is the first post in a series on best practices and tools for open-sourcing a project, based on our experience with Etcher and other such projects. We'll be covering topics including documentation, code quality, community building, error tracking, and so forth. Let us know if there is anything you would like to see!

Documentation is key to a successful open source project. It clearly outlines the scope of the proposed approach and helps developers validate that they are indeed writing for the right solution. Good documentation sends the message that the developers intend their code to be used by others and to keep it healthy.

This blog post discusses one of the most valuable documentation related tools under our belt: JSDoc.

JSDoc is a documentation generator for JavaScript, similar to JavaDoc for Java, or Doxygen for a wide variety of programming languages such as C, C++, Python, Fortran, and more. In a nutshell, JSDoc allows you to place specially-formatted comments above constructs, called annotations, to document their intention and interface. For example:

So essentially, what my utility does is go into your instance of ServiceNow, read certain script files (like script include or ui scripts), dumps them into javascript files, runs jsdoc, jsdoc2md (which creates Markdown files), and runs jshint to do static code analysis. JSDoc Frequently Used annotations. Jsdoc supports following tags and syntax is mentioned. All this syntax should be used included in jsdoc syntax (Adding asterisk to multiline comments) Tag. Usage/Syntax @Author. Adds Author of code, supports to add email. Marks function as a class instance can be created.

We make use of JSDoc heavily at resin.io to aid development and
documentation. This post aims to describe how we use JSDoc and what we strive to get out of it.

Why did we adopt it?

JavaScript projects that make use of annotation comments are rare. There are notable exceptions such as Angular.js and Lodash, but it's not common in the ecosystem, especially on projects that are not strictly re-usable modules. This is a shame, since we've discovered that annotations are crucial for us to deliver high quality maintainable software.

Documentation Driven Development

The clarity and user-friendliness of a piece of code can only be evaluated by seeing it in action. In practice, however, this tends to happen after the code is implemented and coupled to a certain interface. Re-working it takes up valuable time, which often pushes programmers to move on instead of engaging in any refactoring efforts.

We went the extra mile to encourage every developer to write the JSDoc annotations before writing the actual code, since that forces us to think about the API a particular function/class provides before jumping in to write any code. This imposes a reflective phase that solves the majority of simple design problems, such as removing functions without a clear purpose, early on.

In particular, making use of example sections in the annotations allows the developer to experiment with the interface they are planning to expose before diving into its implementation, and therefore provides a fast and cheap design feedback cycle. For this reason, we require every single annotation to include an @example tag, no matter the access type.

Documentation Generation

There is a reason why JSDoc calls itself a 'documentation generator.' The main purpose of tools like this is to mitigate the recurrent problem of documentation getting out of sync with the code, by keeping the details on the code itself and generating documentation out of it.

JSDoc generates HTML-based documentation by default, but we found generating Markdown files to be more accessible to the GitHub-like developer audience, given how such services conveniently display these files. For this purpose, we've set on a fantastic command-line tool called jsdoc-to-markdown.

You can use it to generate documentation from a set of files to a standalone Markdown file, like we do for our Resin SDK:

Or you can even inline documentation into your README.md file, like we do for most of our re-usable modules, by creating a template placed somewhere like doc/README.hbs and providing a documentation section like the following one:

And generating the final README.md with the following command:

See drivelist for an example of this approach, and make sure to check the JSDoc wiki for advanced usage examples.

Lower Barrier to Entry

Having clear annotations for every single function, class, or constant in the code base makes exploring the project and potentially making a contribution much more accessible, both to resin.io team members, as well as to external community members looking to give back to our open source modules. A good combination of JSDoc annotations and inline comments is a valuable resource for quickly getting up to speed.

For this reason, we encourage every developer to write JSDoc annotations even for private constructs, even though we don't generate Markdown documentation out of them, since those are often the chunks of code that tend to get undocumented and not well defined, and thus become inaccessible to people not directly involved with the project.

Writing annotations

Getting familiar with the many supported JSDoc tags and how to combine them to create meaningful annotations might not be trivial at first. For this reason, we've collected as set of examples for how to annotate common JavaScript constructs.

Annotations take the form of C style multiline comments starting with two asterisks:

If you're using CoffeeScript, you can write your annotations like this:

However keep in mind that you're going to have to compile your code into JavaScript before running any JSDoc-related tool on it.

Public Function

Private Function

Constant Variable

Object

Optional Parameter

Object Parameter

Promise

Class

Conclusion

Jsdoc-to-markdown Typescript

We use JSDoc for much more than documentation generation. Comment annotations are an integral part of how we design and implement maintainable software, and provide uniformity across our software projects as well as a low barrier of entry for contributions.

As with any development practice, it takes time to master. In order to make the learning curve easier, we recommend using ESLint, which is able to lint JSDoc annotations and make sure its in sync with the actual code. Check the ESLint JSDoc documentation to see how you can tune your .eslintrc.yml to process your annotations.

Happy documenting!

• 1mark-down

  ˈmɑ:kdaun сущ.
  1) снижение цены
  2) размер уценки (товара) ∙ Syn: markdownскидка с ценыmark-down разницамежду сниженной и старой ценой( товара) ~ снижениецены ~ снижение цены

  Большой англо-русский и русско-английский словарь >mark-down

• 2mark down

  mark down а) снизить цену; занижать (оценку); Some of the salegoods havebeen markeddown by as much as 50%. б) записывать; I markeddown the addressthat she gave me over the telephone, and took carenot to lose it.

  Англо-русский словарь Мюллера >mark down

• 3mark-down

  mark-down noun 1) снижение цены 2) разница между сниженной и старой ценой(товара)

  Англо-русский словарь Мюллера >mark-down

• 4to mark down

  ■ it's marked down to £3el precio está rebajado a tres libras

  3(note in writing) apuntar

  English-spanish dictionary >to mark down

• 5mark-down

  1. मूल्य घटना

  A mark-down of 20% on last month's prices has beenobserved.

  English-Hindi dictionary >mark-down

• 6mark down

  [ma:k d'aun] vt remarcar o preço para baixo, reduzir o preço.

  English-Portuguese dictionary >mark down

• 7mark down

  * * *

  mark down 1) записвам; вписвам (в списък); взимам си бележка от; 2) намалявам цената (на стоки); продавам с намалени цени; 3) поставям по-ниска оценка;

  English-Bulgarian dictionary >mark down

• 8mark down

  1 noteren ⇒ opschrijven

  3 afprijzen

  ♦voorbeelden:

  English-Dutch dictionary >mark down

• 9■ mark down

  ■ mark down

  1annotare; prendere nota di (qc.); segnare:I marked down his phone number, mi sono segnato il suo numero di telefono

  2identificare, credere di riconoscere:The police had marked him down as the thief, but he was innocent, la polizia aveva creduto che fosse lui il ladro, ma era innocente

  3 (market.) abbassare (oridurre, ribassare) il prezzo di (articoli, ecc.)

  4abbassare il voto a (uno studente): DIALOGO → - Coursework-If anyone hands their piece in late they'll get marked down 10%, a chi consegna il lavoro in ritardo viene tolto un 10% dal voto □ (Borsa: di un titolo, ecc.) to be marked down, far segnare un ribasso.

  English-Italian dictionary >■ mark down

• 10mark down

  mark [sth.] down, mark down [sth.] abbassare il prezzo di [product]; mark [sb.] down abbassare i voti a [student]

  vt+adv

  the shirts were marked down at the beginning of the week — le camicie sono state ribassate all'inizio della settimana

  * * *

  mark [sth.] down, mark down [sth.] abbassare il prezzo di [product]; mark [sb.] down abbassare i voti a [student]

  English-Italian dictionary >mark down

• 11mark down

  1) (choose as victim, lit. or fig.) [sich (Dat.)] auswählen; ausersehen (geh.)

  2) [im Preis] herabsetzen [Ware]; herabsetzen [Preis]

  ◆mark down

  1.(reduce the price of)

  ▪to mark down down ⇆ sth etw heruntersetzen [o herabsetzen]

  to mark down down ⇆ sharesSTOCKEX Aktien abwerten

  to mark down down ⇆ exchange ratesSTOCKEX Kurse zurücknehmen

  to mark down down ⇆ the price den Preis herabsetzen [o heruntersetzen

  ▪to mark down down ⇆ sb jdm eine schlechtere Note geben, jdn herunterkorrigieren

  ▪to mark down down ⇆ sth etw notieren

  ▪to mark down down ⇆ sb for sth jdn für etw akk vormerken

  ▪to mark down sb ⇆ down as sth jdn als etw akk einschätzen

  vtsep

  2) prices herab- or heruntersetzen

  mark downv/t

  from … to von … auf akk)

  3. bestimmen, vormerken (beide:

  4. notieren, vermerken

  transitive verb

  1) (choose as victim, lit. or fig.) [sich (Dat.)] auswählen; ausersehen (geh.)

  2) [im Preis] herabsetzen [Ware]; herabsetzen [Preis]

  v.

  aufschreiben v.

  English-german dictionary >mark down

• 12mark down

  mark [something] down, mark down [something] démarquer [product]; mark [somebody] down baisser les notes de [person]

  English-French dictionary >mark down

• 13mark-down

  n. намалување (на цена): a mark-down of 10 % намалување од 10 %

  English-Macedonian dictionary >mark-down

• 14mark down

  1) (reduce price)

  to mark down down <-> sth etw heruntersetzen [o herabsetzen];

  2) (give lower grade)

  to mark down down <-> sb jdm eine schlechtere Note geben [o herunterkorrigieren];

  to mark down down <-> sth etw notieren;

  to mark down sb <-> down as sth jdn als etw einschätzen

  English-German students dictionary >mark down

• 15mark-down

  mark-downS&M Preisherabsetzung f, Preissenkung f (price)

  Englisch-Deutsch Fachwörterbuch der Wirtschaft >mark-down

• 16price mark-down

  Englisch-Deutsch Fachwörterbuch der Wirtschaft >price mark-down

• 17mark down

  1.III

  1) mark down smth. /smth. down/ mark down prices снизить цены; mark down goods (winter coats, woolens, etc.)снизить цены на товары и т.д.

  2) mark down smth. /smth. down/ mark down some figures (some words, etc.)записать цифры и т.д.; now just mark that down in your note-book, it is important запишите это в своем блокноте mark down это очень важно

  3) mark down smb. /smb. down/ mark down the game (one's prey, etc.)выследить дичь и т.д., the look of a tigress that has marked down its prey взгляд тигрицы, выследившей свою жертву

  2.XI

  be marked down these goods have been marked down цены на эти товары снижены /снизили/

  English-Russian dictionary of verb phrases >mark down

• 18mark down

  пометить внизглагол:

  записывать(record, write, write down, save, enter, mark Down)

  снижать цену(cut price, bring down the price, cheapen, depreciate, mark down, underbid)

  отмечать(note, mark, notice, register, flag, mark down)

  Англо-русский синонимический словарь >mark down

• 19mark down

  Персональный Сократ >mark down

• 20mark down

  these goods were marked down — цены на эти товары были снижены

  he was marked down for bad spelling — ему снизили оценку за орфографию

  3.phr v записывать

  who will mark up the score? — кто будет записывать счёт?

  5.phr v выслеживать дичь

  1.cheapen (verb) cheapen; decline; discount; slash

  2.depreciate (verb) decry; depreciate; devalorize; devaluate; devalue; downgrade; soften; underprize; underrate; undervalue; write down; write off

  3.reduce (verb) clip; cut; cut back; cut down; lower; pare; reduce; shave

  English-Russian base dictionary >mark down

• 1

Jsdoc Markdown

См. также в других словарях:

Jsdoc Markdown Template

• mark — 1 verb 1 MAKE A MARK (I, T) to make a mark on something in a way that spoils its appearance, or to become spoiled in this way: We were careful not to mark the paintwork. | The disease had marked her face for life. | It s a beautiful table, but it … Longman dictionary of contemporary English

• mark — ▪ I. mark mark 1 [mɑːk ǁ mɑːrk] noun the £20/​$1000 etc mark 20 pounds, 1000 dollars etc: • There is usually a fee to be paid, generally around the £100 mark plus VAT. [m0] ▪ II. mark mark 2 verb [transitive] to put a sign on something … Financial and business terms

• come — 1 /kVm/ verb past tense came past participle come MOVE 1 (I) a word meaning to move towards someone, or to visit or arrive at a place, used when the person speaking or the person listening is in that place: Come a little closer. | Sarah s coming… … Longman dictionary of contemporary English

• bear — bear1 W1 [beə US ber] v past tense bore [bo: US bo:r] past participle borne [bo:n US bo:rn] [T] ▬▬▬▬▬▬▬ 1¦(deal with something)¦ 2 can t bear something 3 bear (something) in mind 4¦(accept/be responsible for)¦ 5¦(support)¦ 6¦(sign/mark)¦ … Dictionary of contemporary English

• put — W1S1 [put] v past tense and past participle put present participle putting [T] ▬▬▬▬▬▬▬ 1¦(move to place)¦ 2¦(change somebody s situation/feelings)¦ 3¦(write/print something)¦ 4¦(express)¦ 5 put a stop/an end to something 6 put something into… … Dictionary of contemporary English

• set — set1 W1S1 [set] v past tense and past participle set present participle setting ▬▬▬▬▬▬▬ 1¦(put)¦ 2¦(put into surface)¦ 3¦(story)¦ 4¦(consider)¦ 5¦(establish something)¦ 6¦(start something happening)¦ 7¦(decide something)¦ … Dictionary of contemporary English

• hold — hold1 W1S1 [həuld US hould] v past tense and past participle held [held] ▬▬▬▬▬▬▬ 1¦(in your hand/arms)¦ 2¦(event)¦ 3¦(keep something in position)¦ 4¦(job/title)¦ 5¦(keep/store)¦ 6¦(keep something available for somebody)¦ 7¦(keep somebody… … Dictionary of contemporary English

• keep — keep1 W1S1 [ki:p] v past tense and past participle kept [kept] ▬▬▬▬▬▬▬ 1¦(not change)¦ 2¦(continue doing something)¦ 3¦(not give back)¦ 4¦(not lose)¦ 5¦(store something)¦ 6¦(make somebody stay in a place)¦ 7¦(delay somebody)¦ 8¦(do what you… … Dictionary of contemporary English

• turn — turn1 W1S1 [tə:n US tə:rn] v ▬▬▬▬▬▬▬ 1¦(your body)¦ 2¦(object)¦ 3¦(direction)¦ 4¦(move around central point)¦ 5¦(change)¦ 6¦(attention/thoughts)¦ 7 turn your back (on somebody/something) 8¦(age/time)¦ 9 turn something inside out … Dictionary of contemporary English

• track — track1 W2S2 [træk] n ▬▬▬▬▬▬▬ 1¦(path/road)¦ 2¦(marks on ground)¦ 3¦(for racing)¦ 4¦(train)¦ 5 be on the right/wrong track 6 keep/lose track of somebody/something 7¦(music/song)¦ 8 stop/halt (dead) in your tracks 9 cover your tracks … Dictionary of contemporary English

• cut — cut1 W1S1 [kʌt] v past tense and past participle cut present participle cutting ▬▬▬▬▬▬▬ 1¦(reduce)¦ 2¦(divide something with a knife, scissors etc)¦ 3¦(make something shorter with a knife etc)¦ 4¦(remove parts from film etc)¦ 5¦(make a… … Dictionary of contemporary English