{"action":"created","issue":{"url":"https://api.github.com/repos/derekparker/delve/issues/1094","repository_url":"https://api.github.com/repos/derekparker/delve","labels_url":"https://api.github.com/repos/derekparker/delve/issues/1094/labels{/name}","comments_url":"https://api.github.com/repos/derekparker/delve/issues/1094/comments","events_url":"https://api.github.com/repos/derekparker/delve/issues/1094/events","html_url":"https://github.com/derekparker/delve/pull/1094","id":291362045,"number":1094,"title":"[WIP] Internal documentation","user":{"login":"schomatis","id":10407385,"avatar_url":"https://avatars0.githubusercontent.com/u/10407385?v=4","gravatar_id":"","url":"https://api.github.com/users/schomatis","html_url":"https://github.com/schomatis","followers_url":"https://api.github.com/users/schomatis/followers","following_url":"https://api.github.com/users/schomatis/following{/other_user}","gists_url":"https://api.github.com/users/schomatis/gists{/gist_id}","starred_url":"https://api.github.com/users/schomatis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/schomatis/subscriptions","organizations_url":"https://api.github.com/users/schomatis/orgs","repos_url":"https://api.github.com/users/schomatis/repos","events_url":"https://api.github.com/users/schomatis/events{/privacy}","received_events_url":"https://api.github.com/users/schomatis/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":3,"created_at":"2018-01-24T21:14:56Z","updated_at":"2018-02-21T23:29:42Z","closed_at":null,"author_association":"CONTRIBUTOR","pull_request":{"url":"https://api.github.com/repos/derekparker/delve/pulls/1094","html_url":"https://github.com/derekparker/delve/pull/1094","diff_url":"https://github.com/derekparker/delve/pull/1094.diff","patch_url":"https://github.com/derekparker/delve/pull/1094.patch"},"body":"An attempt to contribute to Delve internal's documentation (#1074). This documentation is anchored to version [v1.0.0](https://github.com/derekparker/delve/releases/tag/v1.0.0).\r\n\r\nThe scope now is including the build process, the creation of the server and the debugger, the initialization of the program, the CLI and the interaction between RPC server and client. None of it is described in an exhaustive form.\r\n\r\nAs much as possible the documentation should reside with the code itself in the form of comments rather than in a separate documents. This PR modifies existing go source files, but only adding new (separate) lines with comments and never modifying functionality. \r\n\r\nRight now the focus is on providing the new user the knowledge to navigate Delve's source code from a CLI command of interest into the functionality that supports it. The downside of this approach is that the documentation is being presented in the form of a narration, e.g., \"this command is typed, which calls this function, which send that RPC to that other server, which forwards it to the debugger\". That results in a rather cumbersome text, oriented to much for the new user and not so much for a more advanced one which wants to know the architecture of a specific component inside Delve. Furthermore, the description of many components get rather entangled with each other (because of their natural interaction) and may not result in a clear distinction from each other. The description of the process (or rather the flow of information) is being prioritized over the constituent components of the system. In time part of the descriptions can be refactored out into its own documents.\r\n"},"comment":{"url":"https://api.github.com/repos/derekparker/delve/issues/comments/367514182","html_url":"https://github.com/derekparker/delve/pull/1094#issuecomment-367514182","issue_url":"https://api.github.com/repos/derekparker/delve/issues/1094","id":367514182,"user":{"login":"derekparker","id":1314079,"avatar_url":"https://avatars0.githubusercontent.com/u/1314079?v=4","gravatar_id":"","url":"https://api.github.com/users/derekparker","html_url":"https://github.com/derekparker","followers_url":"https://api.github.com/users/derekparker/followers","following_url":"https://api.github.com/users/derekparker/following{/other_user}","gists_url":"https://api.github.com/users/derekparker/gists{/gist_id}","starred_url":"https://api.github.com/users/derekparker/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/derekparker/subscriptions","organizations_url":"https://api.github.com/users/derekparker/orgs","repos_url":"https://api.github.com/users/derekparker/repos","events_url":"https://api.github.com/users/derekparker/events{/privacy}","received_events_url":"https://api.github.com/users/derekparker/received_events","type":"User","site_admin":false},"created_at":"2018-02-21T23:29:42Z","updated_at":"2018-02-21T23:29:42Z","author_association":"OWNER","body":"@schomatis that seems like a good layout for a high level architectural overview. I think one thing that would be worth mentioning is that all of the actual logic is in the `debugger` package, whose purpose is essentially to abstract all the low-level details of the `proc` package. But the benefit of the `debugger` package holding all the logic is that other APIs can be created, for instance REST, GRPC, and so on. The client / server implementations are dumb on purpose. "}}
{"actor":{"display_login":"derekparker"}}