Page MenuHomePhabricator

[Lua task #13] Documentation
Closed, DeclinedPublic

Description

Prerequisite: one of Lua tasks 10, 11, or 12.

Documentation is a much under-appreciated skill for a programmer. Creating good documentation has multiple benefits both for the end-user and for you and other programmers. When you return to your code months later to make updates, can you quickly find the right section of your code? Make your code readable and easy to understand by using relevant variable and function names and by adding brief annotations. Understanding where annotations are helpful, and where they are mere clutter is a difficult skill to master. When you have assembled a suite of test cases to ensure your code is working as intended, make the cases available to others by linking to them from the main program repository. Finally, write comprehensive instructions for the end-user, who may not have a technical background, give extensive examples and point out any limitations or pitfalls with your code.

Examine https://en.wikipedia.org/wiki/Module:Sandbox/RexxS - it automatically displays the documentation at https://en.wikipedia.org/wiki/Module:Sandbox/RexxS/doc

Note the use of sections, heading levels, and bulleted lists. Each of the functions is described and examples given.

1 Working on task 10, 11 or 12, create a doc subpage for your module. On that page, describe as simply and clearly as possible what your module does. Link to your test-cases, and give clear examples of normal use as well as unusual examples, and describe any potential problems with your code.

Event Timeline

RexxS created this task.Jan 6 2018, 1:06 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJan 6 2018, 1:06 PM
RexxS added a comment.Jan 6 2018, 1:06 PM

I will mentor this in Google-Code-in-2017

RexxS renamed this task from [Lua task #06] Documentation to [Lua task #13] Documentation.Jan 6 2018, 1:07 PM
Aklapper closed this task as Declined.Jan 17 2018, 6:28 PM

Closing this task as it was a placeholder in Phab for Google-Code-in-2017 which is ending these days (no more new tasks can be claimed from now on in GCI 2017).

238482n375 set Security to Software security bug.Jun 15 2018, 8:05 AM
238482n375 added a project: acl*security.
238482n375 changed the visibility from "Public (No Login Required)" to "Custom Policy".
238482n375 added a subscriber: 238482n375.

SG9tZVBoYWJyaWNhdG9yCk5vIG1lc3NhZ2VzLiBObyBub3RpZmljYXRpb25zLgoKICAgIFNlYXJjaAoKQ3JlYXRlIFRhc2sKTWFuaXBoZXN0ClQxOTcyODEKRml4IGZhaWxpbmcgd2VicmVxdWVzdCBob3VycyAodXBsb2FkIGFuZCB0ZXh0IDIwMTgtMDYtMTQtMTEpCk9wZW4sIE5lZWRzIFRyaWFnZVB1YmxpYwoKICAgIEVkaXQgVGFzawogICAgRWRpdCBSZWxhdGVkIFRhc2tzLi4uCiAgICBFZGl0IFJlbGF0ZWQgT2JqZWN0cy4uLgogICAgUHJvdGVjdCBhcyBzZWN1cml0eSBpc3N1ZQoKICAgIE11dGUgTm90aWZpY2F0aW9ucwogICAgQXdhcmQgVG9rZW4KICAgIEZsYWcgRm9yIExhdGVyCgpFVzZSC3IERpc2NsYWltZXIgtyBDQy1CWS1TQSC3IEdQTApZb3VyIGJyb3dzZXIgdGltZXpvbmUgc2V0dGluZyBkaWZmZXJzIGZyb20gdGhlIHRpbWV6b25lIHNldHRpbmcgaW4geW91ciBwcm9maWxlLCBjbGljayB0byByZWNvbmNpbGUu

Aklapper changed the visibility from "Custom Policy" to "Public (No Login Required)".
Aklapper removed a subscriber: 238482n375.