Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
proposal: x/tools/cmd/godoc: GORDO enriched Go documentation format. #35947
Proposal: GORDO enriched Go documentation format.
Author: Ohir Ripe [Wojciech S. Czarnecki]
Last updated: 2019/12/03
Discussion at https://golang.org/issue/35947
GORDO (dʒɔrˈdo) stands for GO Rich DOcs
I propose using a ´gordo´ annotations within the ¨Go¨ source documentation. Gordo enrichment of the source text is unobtrusive even if read in the ˉraw formˉ. Did you notice gordo annotations? These would render:
I propose using a gordo annotations within the Go source documentation. Gordo enrichment of the source text is unobtrusive even if read in the
Current state of Go's source documentation processing is good enough for documenting single implemented things, ie. functions, variables, constants. It falls short if one must convey a new idea, an unobvious implementation of an algorithm, or even just describe a sequence of events (no lists, sadly).
I propose extending godoc processing by a gordo annotations parser implementing both console and html output of described below format.
Documentation that can be styled even with only bold and italics, and one that can be structured to fit the domain, may help package authors to be more precise and unambigous, and help documentation consumers to avoid misunderstandings.
Gordo enabled godoc may encourage a well structured documentation that is written into the program sources even, or the more, for most sophisticated ideas, solutions and code. Now packages of just middle complexity often resort to external descriptions of their api.
Gordo parsing is fast, and there are no ambiguities introduced.
Unlike markdown that makes raw annotated text almost unreadable, the gordo annotations are barely noticeable unless reader is wilfully scanning for the formatting hints.
This proposal extends documentation source syntax, and this syntax parsing methods, in a way that may not influence any program source but — in theory — might alter the visible html output of some existing documentation.
Even if this would happen, such a change would likely effect in the font decoration or size, and would not affect the meaning.
Enabling gordo annotations would need support from both gofmt and godoc. While implementation of basic formatting could be trivial, the real power of the proposed format and methods lie in the ability to make documentation both easy to skim at console and useable as an interactive manual in the browser. The last one needs working internal links between "quotable" and "quote" places implemented as well. Implementing this might need more resources.
There are tons of readily available lightweight markup syntaxes (markdown, asciidoc, reStructuredText, Textile, ...). Why are you proposing yet another markup language?
This seems hard to type. And having to type different things on different operating systems that are translated to various symbols (with a per os
Also using accents in formatting does not make the documents very readable in my personal opinion.
Go docs are meant to be unobtrusive plain text. Obscure Unicode markup does not count as plain text. When reading your example, I did notice the "gordo annotations", but I thought something was wrong with the browser's text rendering. That's not a good thing for documentation.
If we add any more support, it is most likely going to be using a very limited subset of Markdown, like maybe just adopting one bullet list syntax. Even that is still a ways down the priority list though.
Gordo is meant to preserve Go docs to be unobtrusive plain text.
All characters used in gordo came with the brand new DEC's VT100 terminal unit in the year 1983. Thirty six years ago. This set I used in the 1989' software and these characters were available on the dated daisy wheel printers my first client then had.
Used daily with latin letters by a billion people or more.
These will not render in the browser. These might be visible in the source and there they are the least obtrusive. Click through the
Because other markups are obtrusive for anyone who reads them in the source.
Please re-read. I on my side will try to edit this part to have it not being understood exactly the opposite.
It is an user's choice how to type gordo. The example provided in the proposal even shows how to type it using only ASCII characters — just like a markdown.
No. The opposite!
Various characters of user's choice are translated to the fixed set of eleven "gordo" characters.
Author types whatever keystrokes she wants and whatever she finds convenient/avaliable on her national keyboard layout, considering an IDE or editor she uses.
It depends of what one does want to focus on. If it is the markup a reader needs to analyse, then yes - single dots or rings at top of the line need special attention.
Note though, that for all readers but author the less noticeable markup is, the better.
We (me at least) work with source documentation laid out with fixed-width fonts on screens of certain capacity. The html version is important before - lets us read faster and assess quality better. Where I work with other's source, In my vim I have marked parts of the docs (source) four to six keystrokes away.
Gordo aims to be unobtrusive in the source. So to allow it be as readable on the terminal as on the web while keeping the web version searchable and interactive, in a way.