Documentation - Revision history

Adamcolton: /* Mapping */

2020-05-11T16:55:03Z

Mapping

← Older revision		Revision as of 16:55, 11 May 2020
Line 14:		Line 14:
	== Mapping ==		== Mapping ==
	References are bidirectional. Static tools are good at "forward referencing", but sometimes it's just as crucial to know upstream invocations. With in a package this can be done easily enough, but it may be worth including a way to reference "upstream packages" as a way to indicate callers that may be broken by changes.		References are bidirectional. Static tools are good at "forward referencing", but sometimes it's just as crucial to know upstream invocations. With in a package this can be done easily enough, but it may be worth including a way to reference "upstream packages" as a way to indicate callers that may be broken by changes.

			This could be as simple as providing a bit of markup tooling. Referencing "foo.Bar" in the comment will create a link if foo is imported. If not, it can be doc imported with a doc comment by using it's import path.

	[[Category:Gryphon]]		[[Category:Gryphon]]

Adamcolton at 16:51, 11 May 2020

2020-05-11T16:51:33Z

← Older revision		Revision as of 16:51, 11 May 2020
Line 1:		Line 1:
	Integrating documentation into the language is crucial. The barrier to adding documentation should be low and good tooling should be able to weave together documentation with the static information available in the code.		Integrating documentation into the language is crucial. The barrier to adding documentation should be low and good tooling should be able to weave together documentation with the static information available in the code. I would also like to encourage documenting "why does this code exist and who would call it" over "what does it do".

	I'm starting to think that this should be merged with testing and the two exist on a spectrum.		I'm starting to think that this should be merged with testing and the two exist on a spectrum.

Adamcolton at 16:11, 26 November 2019

2019-11-26T16:11:48Z

← Older revision		Revision as of 16:11, 26 November 2019
Line 1:		Line 1:
	Integrating documentation into the language is crucial. The barrier to adding documentation should be low and good tooling should be able to weave together documentation with the static information available in the code.		Integrating documentation into the language is crucial. The barrier to adding documentation should be low and good tooling should be able to weave together documentation with the static information available in the code.

			I'm starting to think that this should be merged with testing and the two exist on a spectrum.

	== Usage ==		== Usage ==

Adamcolton: Created page with "Integrating documentation into the language is crucial. The barrier to adding documentation should be low and good tooling should be able to weave together documentation with ..."

2019-11-26T16:11:10Z

Created page with "Integrating documentation into the language is crucial. The barrier to adding documentation should be low and good tooling should be able to weave together documentation with ..."

New page

Integrating documentation into the language is crucial. The barrier to adding documentation should be low and good tooling should be able to weave together documentation with the static information available in the code.

== Usage ==
This is the basic documentation, how a function is called, what it is intended to do.

== Case Logic ==
Present either in place or as a pointer to a larger document; often at a low level it is difficult to see a larger picture. It is important to have higher level documentation. One risk here is that high level documentation can drift. It would be good to have a review process that can attest that documentation is up to date, even if it hasn't changed. And the ability to highlight documentation that may be out of date.

== Examples ==
I like how Go does this of providing examples that function as both tests and documentation.

== Mapping ==
References are bidirectional. Static tools are good at "forward referencing", but sometimes it's just as crucial to know upstream invocations. With in a package this can be done easily enough, but it may be worth including a way to reference "upstream packages" as a way to indicate callers that may be broken by changes.

[[Category:Gryphon]]