{"action":"created","issue":{"url":"https://api.github.com/repos/panda3d/panda3d/issues/246","repository_url":"https://api.github.com/repos/panda3d/panda3d","labels_url":"https://api.github.com/repos/panda3d/panda3d/issues/246/labels{/name}","comments_url":"https://api.github.com/repos/panda3d/panda3d/issues/246/comments","events_url":"https://api.github.com/repos/panda3d/panda3d/issues/246/events","html_url":"https://github.com/panda3d/panda3d/pull/246","id":296154633,"number":246,"title":"Give p3cull a README","user":{"login":"CFSworks","id":700768,"avatar_url":"https://avatars0.githubusercontent.com/u/700768?v=4","gravatar_id":"","url":"https://api.github.com/users/CFSworks","html_url":"https://github.com/CFSworks","followers_url":"https://api.github.com/users/CFSworks/followers","following_url":"https://api.github.com/users/CFSworks/following{/other_user}","gists_url":"https://api.github.com/users/CFSworks/gists{/gist_id}","starred_url":"https://api.github.com/users/CFSworks/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/CFSworks/subscriptions","organizations_url":"https://api.github.com/users/CFSworks/orgs","repos_url":"https://api.github.com/users/CFSworks/repos","events_url":"https://api.github.com/users/CFSworks/events{/privacy}","received_events_url":"https://api.github.com/users/CFSworks/received_events","type":"User","site_admin":false},"labels":[{"id":712175965,"url":"https://api.github.com/repos/panda3d/panda3d/labels/docs","name":"docs","color":"fef2c0","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":1,"created_at":"2018-02-11T02:50:46Z","updated_at":"2018-02-11T15:59:53Z","closed_at":null,"author_association":"MEMBER","pull_request":{"url":"https://api.github.com/repos/panda3d/panda3d/pulls/246","html_url":"https://github.com/panda3d/panda3d/pull/246","diff_url":"https://github.com/panda3d/panda3d/pull/246.diff","patch_url":"https://github.com/panda3d/panda3d/pull/246.patch"},"body":"This is a first draft at how our component READMEs should probably look. In particular, it follows this formula:\r\n\r\n```\r\np3COMPONENT: Panda3D's COMPONENT THAT DOES SOMETHING\r\n====================================================\r\n\r\nOverview\r\n--------\r\n\r\nTen-foot overview at how the component gets its problem done. Describes interactions between parts. Write this as if someone just asked you \"So how do I start coding on this component?\"\r\n\r\nClasses\r\n-------\r\n\r\n* **SomeClass** is a class that does one thing.\r\n* **OtherClass** is another class that needs SomeClass for something.\r\n\r\nConfiguration\r\n-------------\r\n\r\n* `prc-value #t` turns on prc-value\r\n\r\nBuild-time flags\r\n----------------\r\n\r\n* `WANT_SOME_CLASS` ensures that SomeClass is compiled into the engine providing support for SomeClassery.\r\n* `DO_SOME_CLASS_TRACKING` compiles in support for tracking stats on how SomeClass is used.\r\n```\r\n\r\nNote that I went **way** overboard with the overview section here. A lot of this belongs on the manual, under \"Panda3D Rendering Process\" - only the last section (\"Deciding rendering order\") is really written the way I'd like.\r\n\r\nI'm also aware that a lot of the classes I documented aren't even in p3cull but, rather, in p3pgraph. We should probably fix that. Keeping our components nicely cohesive will make it far easier to find what we're looking for most of the time.\r\n\r\nThis is a pull-request (rather than a direct lob onto `master`) because I'd love to get some feedback and spark a discussion about how in-depth we want to be in our component READMEs. In particular I think they should be highly technical (the target audience is someone reading the C++ code, after all) but I'm open to suggestions about how detailed we go. Again, I went overboard with \"overview,\" since I'm not sure if it's supposed to document _intended_ behavior or _actual_ behavior. The manual seems to go the way of _intended_ behavior - that is, what Panda3D promises to do for the application developer. Component-level READMEs should probably instead have a focus on the component's contract with the rest of the engine.\r\n\r\n(P.S. Even though this is a _pull_ request, it's probably cleaner to cherry-pick it if everyone likes it rather than merge it. It's only one commit after all, so it's cleaner.)"},"comment":{"url":"https://api.github.com/repos/panda3d/panda3d/issues/comments/364762089","html_url":"https://github.com/panda3d/panda3d/pull/246#issuecomment-364762089","issue_url":"https://api.github.com/repos/panda3d/panda3d/issues/246","id":364762089,"user":{"login":"CFSworks","id":700768,"avatar_url":"https://avatars0.githubusercontent.com/u/700768?v=4","gravatar_id":"","url":"https://api.github.com/users/CFSworks","html_url":"https://github.com/CFSworks","followers_url":"https://api.github.com/users/CFSworks/followers","following_url":"https://api.github.com/users/CFSworks/following{/other_user}","gists_url":"https://api.github.com/users/CFSworks/gists{/gist_id}","starred_url":"https://api.github.com/users/CFSworks/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/CFSworks/subscriptions","organizations_url":"https://api.github.com/users/CFSworks/orgs","repos_url":"https://api.github.com/users/CFSworks/repos","events_url":"https://api.github.com/users/CFSworks/events{/privacy}","received_events_url":"https://api.github.com/users/CFSworks/received_events","type":"User","site_admin":false},"created_at":"2018-02-11T15:59:53Z","updated_at":"2018-02-11T15:59:53Z","author_association":"MEMBER","body":"Definitely most/all of my overview section here belongs in a new manual chapter. Feel free to grab it and put it where appropriate. It wasn't until halfway through that I remembered the manual was a thing.\r\n\r\nI suppose the main shift I'm trying to instigate here is a bigger focus on cohesion - perhaps even modularity - and clearer statement of purpose for each component. The component level READMEs should probably be more of a \"guided tour of the codebase\" than an API reference (which belongs in the, you know, API reference) or explanation of engine concepts (which belongs in the manual - perhaps an \"internals\" chapter is in order)\r\n\r\nThe READMEs should probably have as much descriptiveness as necessary for someone to create a full graph (think .dot) of engine interdependencies by hand. I like the class list's emphasis on interaction and external behavior, whereas the API reference tends to have a bigger emphasis on internal behavior.\r\n\r\nI'd say that the question I'm trying to answer here is \"What class do I have to subclass if I want to add my own rendering ordering to the engine?\" and not \"What does CullHandler do?\" - the goal here is to help a new developer, who may have lots of 3D experience but no familiarity with the engine codebase, get up to speed quickly.\r\n\r\nI'm a bit busy today and don't think I can work on a second draft, but perhaps the 3 sections we should have are:\r\n\r\n1) Purpose. Who uses this? What for? Is it exposed to applications or to other Panda components? (Helps maintainers identify dead components like with our cftalk confusion. Helps newcomers know where their new code belongs.)\r\n2) Explanation. If I asked you \"How does your car's camshaft work?\" I'm not expecting a mere list of part numbers for each cam and/or datasheets on them. (\"Each one pushes a lever at some point during one engine cycle.\" doesn't help me work on your car.) I'm mainly wondering about the in-situ purpose of each cam and how it fits with the others. (\"These four open the fuel intakes and are timed to open the cylinder for one quarter cycle half a cycle before ignition, these four are for exhaust, ...\") This helps since a newcomer or even intermediate user doesn't want to read through a class-to-purpose listing in the API reference to find the part of the pipeline that does what they want.\r\n3) Build variables. This might belong somewhere else, I'd concede. But for thorough testing we should have some reference about how the engine changes shape when built differently, so developers who make a change to a component know which build options they need to test with.\r\n\r\nBut as you pointed out, a lot of this can be autogenerated. We might make the rule that the class list is just the first paragraph from each class's doc. That kills two birds with one stone: forces the class doc comments themselves to state their interdependencies and purpose (not just their behavior), and gives us an easy and maintainable way of keeping per-component documentation.\r\n\r\nI like the sphinx generator pulling the README. We should still figure out what that README is. (Just the \"overview\" section? Maybe plus a more friendly name so it shows up as \"Collison handling\" rather than \"p3collide\"?) But yeah, assuming the generator can also grab relevant preprocessor macros, that seems like it addresses every concern."}}
{"actor":{"display_login":"CFSworks"}}