hhvm / user-documentation Goto Github PK

• http://beta.docs.hhvm.com/hack/async/guidelines#considering-data-dependencies-is-important
• http://127.0.0.1:8080/hack/async/guidelines#considering-data-dependencies-is-important
• public/main.css#L46-L48

• HHI defines \KeyedIterable<Tk,Tv> and systemlib defines HH\KeyedIterable<>
• We currently merge these together into HH\KeyedIterable<Tk,Tv>
• This needs to happen for parent classes and interfaces too - eg HH\KeyedIterable<Tk,Tv> needs to extend HH\Iterable<Tv>, not \Iterable<Tv> or HH\Iterable<>

Use the full word Introduction in our page titles.

Also, look at renaming one other page. We have a page called Vs Arrays in the Collections guides. It compares Collections with arrays. Thinking about coming up with a better name.

That flowchart may be accurate, but ... I doubt anyone's ever going to go through that. Might be good to replace it with a simplified version.

Also shouldn't collections work with most built-ins ? Just not next()/key() and apc() ?

Latest iOS.

Instead of Complex, maybe do something with Animals, etc.

Was just skimming http://beta.docs.hhvm.com/hhvm/inconsistencies/introduction and noticed how hard it was to visually parse the hierarchy of sections and subsections. Not sure what the problem is -- maybe the prevalence of code (which is styled differently) in the headers? In any event, I found it a ton harder to read than the markdown original in the HHVM repo's docs dir.

Not sure what the right solution is, just thought it worth pointing out.

Not really part of the docs, but we have a lot of the infra to make this easy

• Will markdown syntax in docblocks render as markdown in the final API reference? It would make the docs look cleaner.
• Parameter types aren't being shown for methods if there aren't put in the docblock. For parameter types that are in docblocks (e.g., AsyncMysqlClient), the types do show. I think we were thinking of deducing the parameter type from the signature instead.
• Empty parameters shouldn't show Parameters heading.
• Alphabetize the listing of the class methods. I think right now they are ordered by how they are reflected upon in the HHI or HNI file, maybe.
• Get any API examples associated with a method to show on the API page (e.g., we have examples for AsyncMysqlXXX and MCRouterXXX classes).
• Everything says "Interface Synopsis" -- can we distinguish between classes, interfaces, etc.
• @internal seems to work not showing the docblock information for a method; but the method signature itself still shows in the docs. We need to link the @internal with not showing the method at all in the API reference.
• do not include private methods
• Render the links to guides when coming across an @guide tag in the docblock.

cc @fredemmott

eg Vector::fromItems()

these do special magic for NULL, which we should demonstrate

Right now we have .hhvm.expect[f] files for all the examples so we can run the test runner on them. But we should also have a .hhvm.output or some file (maybe we can get that through the test runner by keeping the raw output) so that we can show output within the guides themselves too.

We could use the hhvm.expect files for this, but the .hhvm.expectf files have regex wildcards that might not be as useful.

http://staging.docs.hhvm.com/hack/reference/interface/HH.Traversable/

WTF: given that \Traversable is standard PHP, I hope that there isn't really such a thing as HH\Traversable

http://beta.docs.hhvm.com/hack/reference/class/AsyncMysqlConnection/queryf/

It's already in the method documentation itself - it shouldn't be in the example docs.

Right now we have .hhvm.expect[f] files for all the examples so we can run the test runner on them. But we should also have a .hhvm.output or some file (maybe we can get that through the test runner by keeping the raw output) so that we can show output within the guides themselves too.

We could use the hhvm.expect files for this, but the .hhvm.expectf files have regex wildcards that might not be as useful.

But 'Getting' and 'Started' are!

It was fixed in the summary lines; maybe there is a second place that needs fixing.

Current approach: check for <<__HipHopSpecific>>, use of generics/awaitables, or specific namespaces: https://github.com/hhvm/user-documentation/blob/master/src/ScannedDefinitionFilters.php#L10-L34

Also tried using class_exists()/function_exists() and friends: 4f45ba6

I decided not to pursue that approach as a complete PHP build including all extensions needs to be present, which isnt' contributor-friendly.

Via the test runner and standalone as well.

should have examples directories with executable and typecheckable examples

The docs are missing any information and examples of async iterators. First, are they ready to be announced and documented -- I think so? Check with @jano. Second, do we want to document them, since they're such a niche feature -- probably? Third, actually coming up with not-totally-contrived examples and motivation is interesting; I'd probably go for some sort of streaming/reactive API? Or maybe an async API that fetches and returns its results in batches of 10000 or something, since there's a ton of results that are expensive to fetch in aggregate? (AIUI we don't use the feature much at FB, and this last example is one place where we do use it.)

http://beta.docs.hhvm.com/hack/types/refining#refining-types

The "Refining Types" section says:

Suppose you want to take a given type and refine (upcast) that type to another type.

My (amateur) understanding was that:

• Upcasting would be Apple -> Fruit or string -> mixed
• Downcasting would be Fruit -> Apple or ?string -> string

Isn't refinement better described as downcasting?

cc @jamesgpearce @JoelMarcey

From our docs, it sounds like proxygen is a proxy server - all this stuff about proxying requests. Given we use (and proxygen describes itself) as a set of C++ libraries which among other things makes it easy to embed an HTTP server, this seems probably incorrect (unless you consider calling/implementing C++ methods proxying), and at the least confusing.

/hack/operators/placeholder-variable

Is this actually an operator in any way, or just a magic variable?

The following patterns should be converted to links, if the definition exists:

• SomeClass
• foo
• some_function

This should apply to both API and Guide documentation - Guide so that we don't hard-code paths in handwritten markdown, API because if we've already implemented it for the Guide, might as well do it the same :)

it's what this site does, and provides a nicer API. PSR-7 has shortcomings for hack (documented in the HHI readme), but is probably the best option for now.

HHI: https://github.com/fredemmott/psr7-http-message-hhi

Essentially, we want to be able to do this (ignore the specific titles) with the guides to prioritise visual grouping based on skill level of readers:

Right now, there's no hierarchy and it's too confusing and intimidating for beginners imo

eg:

• hh_single_typecheck: almost certainly not what you want
• hh_server --check: not for every day usage, but good for automated tests, commit hooks, etc

The current example has quite a lot of code (and a massive comment about __ConsistentConstruct) so for me it's a bit hard to pick out the important bits being demonstrated.

I think we should focus on:

• Why __ConsistentConstruct is needed
• Returning this from a static method
• Returning this from an instance method (and demonstrate chaining)

http://beta.docs.hhvm.com/hack/types/type-system#this

They don't show up in the navbar as part of the 'Type System' page - this would make them more easily finable

There has been lots of confusion on this point. See, e.g., this SO question: http://stackoverflow.com/a/32937733/3395144

There's a brief discussion of this in the current draft but I think there is still room for improvement. A paragraph discussing this point might be worth it, and I'm especially worried about this sentence:

It allows code that utilizes the async infrastructure to cede CPU time to one another in an explicit and knowing fashion.

This is not typically true; you're going and doing something else instead of blocking on IO, which is not "CPU time" (and the "something else" is probably more IO). Even when it's technically true, when you're busy-waiting, it still gives the wrong impression.

Sorry to nitpick, this is just such a common confusion and such a core feature I think it's worth spending a good bit of time to get this perfect.

From http://beta.docs.hhvm.com/hack/operators/XHP-attribute-access-examples

A link is provided to the XHP doc : http://beta.docs.hhvm.com/hack/xhp/introduction

This link gets me a white screen of death.

Intro

• make it clearer that executing two async functions that call blocking functions (eg non-asio curl_exec()) will not execute curl in parallel. Another picture could be handy for this. An alternative would be to use APIs with more different names for the examples - eg sleep() vs HH\Asio\usleep().

Wait handles

• do we just want to call this 'Awaitables' instead? WaitHandle exists, but isn't what this is talking about - it looks like this section is just defining 'wait handle' to be another word for awaitable?
• 'The type of the Awaitable will be the underlying type that the function would return if it wasn't async' - this is very unclear. The type of the Awaitable will be Awaitable<T>, not T
• The comment in the example seems confusing too:

  // You aren't really returning 2 in the normal sense.
  // You are returning a wait handle that will, upon conclusion of execution,
  // contain the result of 2.
  return 2;

I am not returning an awaitable, I'm returning 2. The Awaitable part applies to the whole function, not just the return statement.

Not quite sure where to put this.

Install docker, then:

docker pull hhvm/user-documentation
docker run -p 1234:80 hhvm/user-documentation

Open http://localhost:1234 in your browser

e.g., v(), m(), etc.

This list contains the actual user-content tasks that need to be completed. Choose a topic, comment on this issue with the topic you will be working on, write great content, get it peer-reviewed and check the box off when completed.

IMPORTANT: Please follow the contribution guidelines when adding or modifying content.

NOTE: Feel free to add to or modify this list as appropriate as we move along in our efforts here. This is just the initial skeleton guide of how we should approach the docs. It can change, of course.

NOTE: All the Hack markdown .md placeholders are in hack/<##-topic> and the HHVM placeholders are in hhvm/<##-topic>, where ## represents a table of contents placeholder suitable for documentation generation tooling. Obviously feel free to add or change any of the placeholders to better suit your documentation efforts.

NOTE: @fredemmott is creating the infra to tie all of the content documentation in our markdown files with the API documentation.

• Hack Quickstart (@JoelMarcey)
  • Types (@JoelMarcey)
  • Generics (@RexJaeschke, @int3)
  • Async (@JoelMarcey)
  • Collections (@JoelMarcey)
  • XHP (@JoelMarcey)
  • Type Aliases (@RexJaeschke)
  • Lambdas (@SiebelsTim, @JoelMarcey)
  • Shapes (@RexJaeschke)
  • Type Constants (@JoelMarcey)
  • Operators (@JoelMarcey)
  • Attributes (@JoelMarcey)
  • Enums (@JoelMarcey)
  • Callables (@JoelMarcey)
  • Other Features (@JoelMarcey)
  • Unsupported Features (@JoelMarcey)
  • Typechecker (@JoelMarcey)
  • Tools (@JoelMarcey)
  • FAQ (@JoelMarcey)
  • API Examples
    • AsyncMySQL (@JoelMarcey)
    • Collections (@JoelMarcey)
    • Asio (@JoelMarcey)
    • McRouter (@JoelMarcey)
• HHVM Quickstart (@JoelMarcey)
  • Installation (@JoelMarcey)
  • Configuration (@JoelMarcey)
    • INI Settings (@JoelMarcey)
  • Deployment (@JoelMarcey)
  • Using Extensions (@JoelMarcey)
  • Inconsistencies to PHP (@JoelMarcey)
  • FAQ (@JoelMarcey)
• Other
  • Update Test Runner to support running the typechecker and .typechecker.expect[f] and .hhvm.expect[f] (@JoelMarcey)
  • Document Collections Interfaces via docblocks in hphp/hack/hhi/collections/interfaces.hhi

Right now we use markdown within hhi, hni files to help produce nicely readable API documentation.

But in order to avoid massive bloat within the docblocks, I didn't add [....](.....) links every time a class or method was mentioned -- but we do mention other classes and methods quite a bit from a class or method docblock.

Is there a way to use our yaml or other infrastructure to automatically add links whenever we encounter

CLASS

in a docblock?

It would be more friendly to users for them to be able to click to other places from within the descriptions of the API docs.

Hey all, been trying to get the guide to build locally but haven't been able to.

2015-11-12 22:12:56] Build sources for /Users/jmcfarland/code/hack/user-documentation/build/systemlib............
Fatal error: Uncaught exception 'HH\InvariantException' with message 'expected type constraint at line 8' in /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/consumers/GenericsConsumer.php:87
Stack trace:
#0 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/consumers/GenericsConsumer.php(87): HH\invariant_violation()
#1 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/consumers/ClassConsumer.php(45): FredEmmott\DefinitionFinder\GenericsConsumer->getGenerics()
#2 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/consumers/ScopeConsumer.php(158): FredEmmott\DefinitionFinder\ClassConsumer->getBuilder()
#3 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/consumers/ScopeConsumer.php(126): FredEmmott\DefinitionFinder\ScopeConsumer->consumeDefinition()
#4 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/consumers/NamespaceConsumer.php(32): FredEmmott\DefinitionFinder\ScopeConsumer->getBuilder()
#5 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/consumers/ScopeConsumer.php(151): FredEmmott\DefinitionFinder\NamespaceConsumer->getBuilder()
#6 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/consumers/ScopeConsumer.php(126): FredEmmott\DefinitionFinder\ScopeConsumer->consumeDefinition()
#7 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/FileParser.php(11): FredEmmott\DefinitionFinder\ScopeConsumer->getBuilder()
#8 /Users/jmcfarland/code/hack/user-documentation/vendor/fredemmott/definition-finder/src/FileParser.php(31): FredEmmott\DefinitionFinder\FileParser->__construct()
#9 /Users/jmcfarland/code/hack/user-documentation/src/build/RawYAMLBuildStep.php(41): FredEmmott\DefinitionFinder\FileParser::FromData()
#10 /Users/jmcfarland/code/hack/user-documentation/src/build/RawYAMLBuildStep.php(15): HHVM\UserDocumentation\RawYAMLBuildStep->buildSources()
#11 /Users/jmcfarland/code/hack/user-documentation/bin/build.php(6): HHVM\UserDocumentation\RawYAMLBuildStep->buildAll()
#12 /Users/jmcfarland/code/hack/user-documentation/bin/build.php(14): HHVM\UserDocumentation\hhvm_to_yaml()
#13 {main}

It gets through a few steps before hitting this. I have the master branch checked out, going to try it with the HHVM-3.10 branch.

My ideal: every file has # as the top level heading. If given it's context it should be an h2 instead, this can be handled in the markdown renderer. This means that we can change generic structure of the page without having to rewrite all the docs.

It makes sense to read a lot of the guides in order; a 'Next' button at the bottom would be useful.

• clarify that hhvm/asio-utilities is only supported and needed for HHVM < 3.11
• Make it clear that these functions are all HH\Asio\foo() instead of just foo()
• 'But there exists a whole collection of concise' is awkward wording
• 'simply named' is tenuous - concisely and consistently named is accurate :p
• In typechecking gotcha section, possibly suggest workarounds, eg https://github.com/hhvm/user-documentation/blob/7568764b587b24f3a8441bee1f1ac6940cb5de7e/src/utils/async_funcs.php

eg I see HH.Invariant instead of HH\Invariant