{"action":"created","comment":{"url":"https://api.github.com/repos/chapel-lang/chapel/pulls/comments/25360752","id":25360752,"diff_hunk":"@@ -0,0 +1,273 @@\n+/*\n+ * Copyright 2004-2015 Cray Inc.\n+ * Other additional copyright holders may be indicated within.\n+ *\n+ * The entirety of this work is licensed under the Apache License,\n+ * Version 2.0 (the \"License\"); you may not use this file except\n+ * in compliance with the License.\n+ *\n+ * You may obtain a copy of the License at\n+ *\n+ *     http://www.apache.org/licenses/LICENSE-2.0\n+ *\n+ * Unless required by applicable law or agreed to in writing, software\n+ * distributed under the License is distributed on an \"AS IS\" BASIS,\n+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n+ * See the License for the specific language governing permissions and\n+ * limitations under the License.\n+ */\n+\n+#include <fstream>\n+#include <iostream>\n+#include <stack>\n+#include <string>\n+#include <sys/stat.h>\n+\n+#include \"AstPrintDocs.h\"\n+\n+#include \"symbol.h\"\n+#include \"type.h\"\n+\n+\n+AstPrintDocs::AstPrintDocs(std::ostream *file) :\n+  file(file),\n+  tabs(0)\n+{\n+}\n+\n+\n+AstPrintDocs::~AstPrintDocs() {\n+}\n+\n+\n+//\n+// Methods needed by this visitor.\n+//\n+\n+\n+bool AstPrintDocs::enterAggrType(AggregateType* node) {\n+  // If class/record is not supposed to be documented, do not traverse into it\n+  // (and skip the documentation).\n+  if (node->symbol->hasFlag(FLAG_NO_DOC)) {\n+    return false;\n+  }\n+\n+  node->printDocs(this->file, this->tabs);\n+  this->tabs++;\n+  return true;\n+}\n+\n+\n+void AstPrintDocs::exitAggrType(AggregateType* node) {\n+  // If class/record is not supposed to be documented, it was not traversed\n+  // into or documented, so exit early from this method.\n+  if (node->symbol->hasFlag(FLAG_NO_DOC)) {\n+    return;\n+  }\n+\n+  // TODO: Does it make sense to print inheritance here?\n+  //       (thomasvandoren, 2015-02-22)\n+  this->tabs--;\n+}\n+\n+\n+bool AstPrintDocs::enterFnSym(FnSymbol* node) {\n+  node->printDocs(file, this->tabs);\n+  return false;","path":"compiler/AST/AstPrintDocs.cpp","position":76,"original_position":76,"commit_id":"2e996ceb82ddf2f982eeb421f605637c4033437f","original_commit_id":"75d11e425fad163908f6898d0d8c13c8a4fafad8","user":{"login":"lydia-duncan","id":2454710,"avatar_url":"https://avatars.githubusercontent.com/u/2454710?v=3","gravatar_id":"","url":"https://api.github.com/users/lydia-duncan","html_url":"https://github.com/lydia-duncan","followers_url":"https://api.github.com/users/lydia-duncan/followers","following_url":"https://api.github.com/users/lydia-duncan/following{/other_user}","gists_url":"https://api.github.com/users/lydia-duncan/gists{/gist_id}","starred_url":"https://api.github.com/users/lydia-duncan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lydia-duncan/subscriptions","organizations_url":"https://api.github.com/users/lydia-duncan/orgs","repos_url":"https://api.github.com/users/lydia-duncan/repos","events_url":"https://api.github.com/users/lydia-duncan/events{/privacy}","received_events_url":"https://api.github.com/users/lydia-duncan/received_events","type":"User","site_admin":false},"body":"Ah, that makes sense.","created_at":"2015-02-25T17:41:41Z","updated_at":"2015-02-25T17:41:41Z","html_url":"https://github.com/chapel-lang/chapel/pull/1369#discussion_r25360752","pull_request_url":"https://api.github.com/repos/chapel-lang/chapel/pulls/1369","_links":{"self":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/comments/25360752"},"html":{"href":"https://github.com/chapel-lang/chapel/pull/1369#discussion_r25360752"},"pull_request":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/1369"}}},"pull_request":{"url":"https://api.github.com/repos/chapel-lang/chapel/pulls/1369","id":29775888,"html_url":"https://github.com/chapel-lang/chapel/pull/1369","diff_url":"https://github.com/chapel-lang/chapel/pull/1369.diff","patch_url":"https://github.com/chapel-lang/chapel/pull/1369.patch","issue_url":"https://api.github.com/repos/chapel-lang/chapel/issues/1369","number":1369,"state":"open","locked":false,"title":"chpldoc outputs docs in same order as source files.","user":{"login":"thomasvandoren","id":530981,"avatar_url":"https://avatars.githubusercontent.com/u/530981?v=3","gravatar_id":"","url":"https://api.github.com/users/thomasvandoren","html_url":"https://github.com/thomasvandoren","followers_url":"https://api.github.com/users/thomasvandoren/followers","following_url":"https://api.github.com/users/thomasvandoren/following{/other_user}","gists_url":"https://api.github.com/users/thomasvandoren/gists{/gist_id}","starred_url":"https://api.github.com/users/thomasvandoren/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/thomasvandoren/subscriptions","organizations_url":"https://api.github.com/users/thomasvandoren/orgs","repos_url":"https://api.github.com/users/thomasvandoren/repos","events_url":"https://api.github.com/users/thomasvandoren/events{/privacy}","received_events_url":"https://api.github.com/users/thomasvandoren/received_events","type":"User","site_admin":false},"body":"Update docs() pass to output the documentation in the same order as\r\nthe original source files.\r\n\r\nMove several of the string utilities previously in docs.cpp into stringutil.cpp\r\nso they can be used elsewhere in the compiler.\r\n\r\nMove the logic for printing a particular symbol or class to actual object. For\r\nexample, VarSymbol now has a printDocs(file, tabs) method that prints out\r\nthe text or rst content for itself. VarSymbol, FnSymbol, ModSymbol, and\r\nAggregateType have printDocs() methods. VarSymbol, FnSymbol, and\r\nAggregateType have docsDirective() methods, which return the rst directive\r\nor text prefix for the instance.\r\n\r\nUpdate ModuleSymbol with docsName() and addPrefixToName() methods.\r\naddPrefixToName() records the parent module names and docsName()\r\nreturns the prefix concatenated with the instance's name. Add method to\r\nAggregateType, printInheritanceDocs(), that prints the \"inherited from\r\n<name>\" section.\r\n\r\nUpdate VarSymbol with new makeField() method that sets private bool\r\nmember 'isField' to true. Update AggregateType::addDeclaration to call\r\nmakeField() on VarSymbols. This allows a VarSymbol to detect if it is a\r\nglobal or a class/record member.\r\n\r\nUpdate BaseAst with two methods and a static const member for printing\r\n\"tabs\" and symbol descriptions. BaseAST::tabText is a static const string\r\nthat is used for indentation. It continues to be 3 spaces. printTabs(file, tabs)\r\nadds the indentation to file. printDocsDescription(docs, file, tabs) takes a\r\ndoc string for a symbol, cleans it up using the ltrim() et al methods that\r\nused to be in docs.cpp and prints it to file. printDocsDescription() must take\r\nthe docs string as an argument because BaseAST does not define a docs\r\nmember.\r\n\r\nAdd new visitor, AstPrintDocs, which has members for a file handle and\r\ntab count. The enter/visit methods call the respective printDocs() for\r\nVarSymbol, FnSymbol, AggregateType, and ModSymbol. When this visitor\r\nis passed to ModSymbol::accept(), the docs are output in source order.\r\n\r\nUpdate docs() pass to use the printDocs() instance methods and remove\r\nthe code that printDocs() methods were based on. For now, I have left in the\r\nfunctions that output the docs in logical groupings and alphabetical order.\r\nThe docs() pass does not call them, but they still work (test it by commenting\r\nout the visitor and uncommenting the printModule(file, mod, mod->name) call\r\ninside docs()). In the future (maybe near/medium ish) we can add flags that\r\nallow the caller to choose which ordering they want, which is why I preserved\r\nthem.\r\n\r\nUpdate the class/record signatures to include any inherited symbols. If C\r\ninherits A, its signature will now be \"class C : A\". Multiple inheritance is\r\nsupported by joining all inherited classes in a comma delimited list. E.g. if C\r\ninherits from both B and A, its signature will be \"class C: B, A\".\r\n\r\nRemove the \"inherited from super_class_name\" and additional inherited\r\nmembers and methods from class/records. This simplifies the AggregateType\r\nvisitor method as it no longer has to realize all the inherited symbols in order to\r\nprint the docs for itself. It also avoids the duplicate documentation for overridden\r\nmethods and members.\r\n\r\nIn order to make sure the printDocs() methods exhibited the same behavior,\r\nI ran start_test on test/chpldoc/ using the commented out code for logical\r\ngroupings. All the chpldoc/ tests passed, so I am confident this only changes\r\nthe ordering and not the formatting of any one symbol.\r\n\r\nUpdate 16 .good files under test/chpldoc/ that changed due to the ordering.\r\nAlso, mark all test/chpldoc/compflags/alphabetical/ tests as NOTEST, since\r\nthe alphabetical ordering does not work with this change. Also, update tests\r\nthat included inheritance to match new output.\r\n\r\n### TODO:\r\n\r\n* [x] ensure existing formatting is preserved by running start_test over\r\n  test/chpldoc with the old ordering (will test that printDocs() methods output\r\n  same format as before and using visitor is really just a change in ordering).\r\n* [x] update chpldoc/ tests for new source based ordering (saved the\r\n   existing .good files, though, for later).\r\n* [x] full test pass (default config on linux64 and LLVM).\r\n","created_at":"2015-02-22T20:13:06Z","updated_at":"2015-02-25T17:41:41Z","closed_at":null,"merged_at":null,"merge_commit_sha":"1c09fbfbc2842083d726f0fff5410a8e6a12034b","assignee":{"login":"lydia-duncan","id":2454710,"avatar_url":"https://avatars.githubusercontent.com/u/2454710?v=3","gravatar_id":"","url":"https://api.github.com/users/lydia-duncan","html_url":"https://github.com/lydia-duncan","followers_url":"https://api.github.com/users/lydia-duncan/followers","following_url":"https://api.github.com/users/lydia-duncan/following{/other_user}","gists_url":"https://api.github.com/users/lydia-duncan/gists{/gist_id}","starred_url":"https://api.github.com/users/lydia-duncan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lydia-duncan/subscriptions","organizations_url":"https://api.github.com/users/lydia-duncan/orgs","repos_url":"https://api.github.com/users/lydia-duncan/repos","events_url":"https://api.github.com/users/lydia-duncan/events{/privacy}","received_events_url":"https://api.github.com/users/lydia-duncan/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/chapel-lang/chapel/pulls/1369/commits","review_comments_url":"https://api.github.com/repos/chapel-lang/chapel/pulls/1369/comments","review_comment_url":"https://api.github.com/repos/chapel-lang/chapel/pulls/comments{/number}","comments_url":"https://api.github.com/repos/chapel-lang/chapel/issues/1369/comments","statuses_url":"https://api.github.com/repos/chapel-lang/chapel/statuses/2e996ceb82ddf2f982eeb421f605637c4033437f","head":{"label":"thomasvandoren:docs-source-based-order","ref":"docs-source-based-order","sha":"2e996ceb82ddf2f982eeb421f605637c4033437f","user":{"login":"thomasvandoren","id":530981,"avatar_url":"https://avatars.githubusercontent.com/u/530981?v=3","gravatar_id":"","url":"https://api.github.com/users/thomasvandoren","html_url":"https://github.com/thomasvandoren","followers_url":"https://api.github.com/users/thomasvandoren/followers","following_url":"https://api.github.com/users/thomasvandoren/following{/other_user}","gists_url":"https://api.github.com/users/thomasvandoren/gists{/gist_id}","starred_url":"https://api.github.com/users/thomasvandoren/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/thomasvandoren/subscriptions","organizations_url":"https://api.github.com/users/thomasvandoren/orgs","repos_url":"https://api.github.com/users/thomasvandoren/repos","events_url":"https://api.github.com/users/thomasvandoren/events{/privacy}","received_events_url":"https://api.github.com/users/thomasvandoren/received_events","type":"User","site_admin":false},"repo":{"id":21669387,"name":"chapel","full_name":"thomasvandoren/chapel","owner":{"login":"thomasvandoren","id":530981,"avatar_url":"https://avatars.githubusercontent.com/u/530981?v=3","gravatar_id":"","url":"https://api.github.com/users/thomasvandoren","html_url":"https://github.com/thomasvandoren","followers_url":"https://api.github.com/users/thomasvandoren/followers","following_url":"https://api.github.com/users/thomasvandoren/following{/other_user}","gists_url":"https://api.github.com/users/thomasvandoren/gists{/gist_id}","starred_url":"https://api.github.com/users/thomasvandoren/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/thomasvandoren/subscriptions","organizations_url":"https://api.github.com/users/thomasvandoren/orgs","repos_url":"https://api.github.com/users/thomasvandoren/repos","events_url":"https://api.github.com/users/thomasvandoren/events{/privacy}","received_events_url":"https://api.github.com/users/thomasvandoren/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/thomasvandoren/chapel","description":"a Productive Parallel Programming Language","fork":true,"url":"https://api.github.com/repos/thomasvandoren/chapel","forks_url":"https://api.github.com/repos/thomasvandoren/chapel/forks","keys_url":"https://api.github.com/repos/thomasvandoren/chapel/keys{/key_id}","collaborators_url":"https://api.github.com/repos/thomasvandoren/chapel/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/thomasvandoren/chapel/teams","hooks_url":"https://api.github.com/repos/thomasvandoren/chapel/hooks","issue_events_url":"https://api.github.com/repos/thomasvandoren/chapel/issues/events{/number}","events_url":"https://api.github.com/repos/thomasvandoren/chapel/events","assignees_url":"https://api.github.com/repos/thomasvandoren/chapel/assignees{/user}","branches_url":"https://api.github.com/repos/thomasvandoren/chapel/branches{/branch}","tags_url":"https://api.github.com/repos/thomasvandoren/chapel/tags","blobs_url":"https://api.github.com/repos/thomasvandoren/chapel/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/thomasvandoren/chapel/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/thomasvandoren/chapel/git/refs{/sha}","trees_url":"https://api.github.com/repos/thomasvandoren/chapel/git/trees{/sha}","statuses_url":"https://api.github.com/repos/thomasvandoren/chapel/statuses/{sha}","languages_url":"https://api.github.com/repos/thomasvandoren/chapel/languages","stargazers_url":"https://api.github.com/repos/thomasvandoren/chapel/stargazers","contributors_url":"https://api.github.com/repos/thomasvandoren/chapel/contributors","subscribers_url":"https://api.github.com/repos/thomasvandoren/chapel/subscribers","subscription_url":"https://api.github.com/repos/thomasvandoren/chapel/subscription","commits_url":"https://api.github.com/repos/thomasvandoren/chapel/commits{/sha}","git_commits_url":"https://api.github.com/repos/thomasvandoren/chapel/git/commits{/sha}","comments_url":"https://api.github.com/repos/thomasvandoren/chapel/comments{/number}","issue_comment_url":"https://api.github.com/repos/thomasvandoren/chapel/issues/comments{/number}","contents_url":"https://api.github.com/repos/thomasvandoren/chapel/contents/{+path}","compare_url":"https://api.github.com/repos/thomasvandoren/chapel/compare/{base}...{head}","merges_url":"https://api.github.com/repos/thomasvandoren/chapel/merges","archive_url":"https://api.github.com/repos/thomasvandoren/chapel/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/thomasvandoren/chapel/downloads","issues_url":"https://api.github.com/repos/thomasvandoren/chapel/issues{/number}","pulls_url":"https://api.github.com/repos/thomasvandoren/chapel/pulls{/number}","milestones_url":"https://api.github.com/repos/thomasvandoren/chapel/milestones{/number}","notifications_url":"https://api.github.com/repos/thomasvandoren/chapel/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/thomasvandoren/chapel/labels{/name}","releases_url":"https://api.github.com/repos/thomasvandoren/chapel/releases{/id}","created_at":"2014-07-09T21:14:48Z","updated_at":"2015-02-15T23:22:21Z","pushed_at":"2015-02-25T16:43:13Z","git_url":"git://github.com/thomasvandoren/chapel.git","ssh_url":"git@github.com:thomasvandoren/chapel.git","clone_url":"https://github.com/thomasvandoren/chapel.git","svn_url":"https://github.com/thomasvandoren/chapel","homepage":"http://chapel.cray.com/","size":271367,"stargazers_count":1,"watchers_count":1,"language":"Chapel","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":1,"default_branch":"master"}},"base":{"label":"chapel-lang:master","ref":"master","sha":"c8b74e16559cbcb884c8fd9d7ffc0d0c141dd119","user":{"login":"chapel-lang","id":7597261,"avatar_url":"https://avatars.githubusercontent.com/u/7597261?v=3","gravatar_id":"","url":"https://api.github.com/users/chapel-lang","html_url":"https://github.com/chapel-lang","followers_url":"https://api.github.com/users/chapel-lang/followers","following_url":"https://api.github.com/users/chapel-lang/following{/other_user}","gists_url":"https://api.github.com/users/chapel-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/chapel-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chapel-lang/subscriptions","organizations_url":"https://api.github.com/users/chapel-lang/orgs","repos_url":"https://api.github.com/users/chapel-lang/repos","events_url":"https://api.github.com/users/chapel-lang/events{/privacy}","received_events_url":"https://api.github.com/users/chapel-lang/received_events","type":"Organization","site_admin":false},"repo":{"id":21663285,"name":"chapel","full_name":"chapel-lang/chapel","owner":{"login":"chapel-lang","id":7597261,"avatar_url":"https://avatars.githubusercontent.com/u/7597261?v=3","gravatar_id":"","url":"https://api.github.com/users/chapel-lang","html_url":"https://github.com/chapel-lang","followers_url":"https://api.github.com/users/chapel-lang/followers","following_url":"https://api.github.com/users/chapel-lang/following{/other_user}","gists_url":"https://api.github.com/users/chapel-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/chapel-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chapel-lang/subscriptions","organizations_url":"https://api.github.com/users/chapel-lang/orgs","repos_url":"https://api.github.com/users/chapel-lang/repos","events_url":"https://api.github.com/users/chapel-lang/events{/privacy}","received_events_url":"https://api.github.com/users/chapel-lang/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/chapel-lang/chapel","description":"a Productive Parallel Programming Language","fork":false,"url":"https://api.github.com/repos/chapel-lang/chapel","forks_url":"https://api.github.com/repos/chapel-lang/chapel/forks","keys_url":"https://api.github.com/repos/chapel-lang/chapel/keys{/key_id}","collaborators_url":"https://api.github.com/repos/chapel-lang/chapel/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/chapel-lang/chapel/teams","hooks_url":"https://api.github.com/repos/chapel-lang/chapel/hooks","issue_events_url":"https://api.github.com/repos/chapel-lang/chapel/issues/events{/number}","events_url":"https://api.github.com/repos/chapel-lang/chapel/events","assignees_url":"https://api.github.com/repos/chapel-lang/chapel/assignees{/user}","branches_url":"https://api.github.com/repos/chapel-lang/chapel/branches{/branch}","tags_url":"https://api.github.com/repos/chapel-lang/chapel/tags","blobs_url":"https://api.github.com/repos/chapel-lang/chapel/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/chapel-lang/chapel/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/chapel-lang/chapel/git/refs{/sha}","trees_url":"https://api.github.com/repos/chapel-lang/chapel/git/trees{/sha}","statuses_url":"https://api.github.com/repos/chapel-lang/chapel/statuses/{sha}","languages_url":"https://api.github.com/repos/chapel-lang/chapel/languages","stargazers_url":"https://api.github.com/repos/chapel-lang/chapel/stargazers","contributors_url":"https://api.github.com/repos/chapel-lang/chapel/contributors","subscribers_url":"https://api.github.com/repos/chapel-lang/chapel/subscribers","subscription_url":"https://api.github.com/repos/chapel-lang/chapel/subscription","commits_url":"https://api.github.com/repos/chapel-lang/chapel/commits{/sha}","git_commits_url":"https://api.github.com/repos/chapel-lang/chapel/git/commits{/sha}","comments_url":"https://api.github.com/repos/chapel-lang/chapel/comments{/number}","issue_comment_url":"https://api.github.com/repos/chapel-lang/chapel/issues/comments{/number}","contents_url":"https://api.github.com/repos/chapel-lang/chapel/contents/{+path}","compare_url":"https://api.github.com/repos/chapel-lang/chapel/compare/{base}...{head}","merges_url":"https://api.github.com/repos/chapel-lang/chapel/merges","archive_url":"https://api.github.com/repos/chapel-lang/chapel/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/chapel-lang/chapel/downloads","issues_url":"https://api.github.com/repos/chapel-lang/chapel/issues{/number}","pulls_url":"https://api.github.com/repos/chapel-lang/chapel/pulls{/number}","milestones_url":"https://api.github.com/repos/chapel-lang/chapel/milestones{/number}","notifications_url":"https://api.github.com/repos/chapel-lang/chapel/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/chapel-lang/chapel/labels{/name}","releases_url":"https://api.github.com/repos/chapel-lang/chapel/releases{/id}","created_at":"2014-07-09T18:15:54Z","updated_at":"2015-02-25T16:43:12Z","pushed_at":"2015-02-25T16:43:11Z","git_url":"git://github.com/chapel-lang/chapel.git","ssh_url":"git@github.com:chapel-lang/chapel.git","clone_url":"https://github.com/chapel-lang/chapel.git","svn_url":"https://github.com/chapel-lang/chapel","homepage":"http://chapel.cray.com/","size":333558,"stargazers_count":68,"watchers_count":68,"language":"Chapel","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":37,"mirror_url":null,"open_issues_count":11,"forks":37,"open_issues":11,"watchers":68,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/1369"},"html":{"href":"https://github.com/chapel-lang/chapel/pull/1369"},"issue":{"href":"https://api.github.com/repos/chapel-lang/chapel/issues/1369"},"comments":{"href":"https://api.github.com/repos/chapel-lang/chapel/issues/1369/comments"},"review_comments":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/1369/comments"},"review_comment":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/chapel-lang/chapel/pulls/1369/commits"},"statuses":{"href":"https://api.github.com/repos/chapel-lang/chapel/statuses/2e996ceb82ddf2f982eeb421f605637c4033437f"}}}}