f3f0b1141078c182102af7c0d34f5e8dd5f9eab8 braney Thu Feb 21 11:56:59 2013 -0800 clean up comments to start with a capital and end with a period (per code review #10237) diff --git src/hg/lib/trackHub.c src/hg/lib/trackHub.c index 0f0104a..7bd3fc1 100644 --- src/hg/lib/trackHub.c +++ src/hg/lib/trackHub.c @@ -60,312 +60,314 @@ return htmlExpandUrl(hubUrl, path); /* If we got to here hub is local, and so is path. Do standard * path parsing. */ return pathRelativeToFile(hubUrl, path); } static void badGenomeStanza(struct lineFile *lf) /* Put up semi-informative error message about a genome stanza being bad. */ { errAbort("Genome stanza should have exactly two lines, one with 'genome' and one with 'trackDb'\n" "Bad stanza format ending line %d of %s", lf->lineIx, lf->fileName); } char *trackHubCladeToGenome(char *clade) -/* given a track hub clade(hub name) return the default genome */ +/* Given a track hub clade(hub name) return the default genome. */ { if (hubCladeHash == NULL) return FALSE; struct hashEl *hel = hashLookup(hubCladeHash, clade); if (hel == NULL) return FALSE; struct trackHub *trackHub = hel->val; struct trackHubGenome *hubGenome = trackHub->genomeList; for(; hubGenome; hubGenome=hubGenome->next) if (hubGenome->twoBitPath != NULL) return hubGenome->organism ; return NULL; } boolean trackHubDatabase(char *database) -/* is this an assembly from an Assembly Data hub? */ +/* Is this an assembly from an Assembly Data hub? */ { if (hubAssemblyHash == NULL) return FALSE; struct hashEl *hel = hashLookup(hubAssemblyHash, database); if (hel == NULL) return FALSE; return TRUE; } char *trackHubAssemblyField(char *database, char *field) -/* get data field from a assembly data hub */ +/* Get data field from a assembly data hub. */ { struct hashEl *hel = hashLookup(hubAssemblyHash, database); if (hel == NULL) return NULL; struct trackHubGenome *genome = hel->val; char *ret = hashFindVal(genome->settingsHash, field); return cloneString(ret); } static struct dbDb *makeDbDbFromAssemblyGenome(struct trackHubGenome *hubGenome) +/* Make a dbdb struture from a single assembly hub database. */ { struct dbDb *db; AllocVar(db); db->genome = cloneString(hubGenome->organism); db->organism = cloneString(hubGenome->organism); db->name = cloneString(hubGenome->name); db->active = TRUE; db->description = cloneString(hubGenome->description); return db; } struct dbDb *trackHubDbDbFromAssemblyDb(char *database) -/* return a dbDb structure for just this database */ +/* Return a dbDb structure for just this database. */ { struct hashEl *hel = hashLookup(hubAssemblyHash, database); if (hel == NULL) return NULL; struct trackHubGenome *genome = hel->val; return makeDbDbFromAssemblyGenome(genome); } struct slPair *trackHubGetHubLabels() -/* get a list of labels describing the loaded assembly data hubs */ +/* Get a list of labels describing the loaded assembly data hubs. */ { if (globalAssemblyHubList == NULL) return NULL; struct slPair *clade, *cladeList = NULL; struct trackHub *trackHub = globalAssemblyHubList; for(;trackHub; trackHub = trackHub->next) { AllocVar(clade); slAddHead(&cladeList, clade); clade->name = cloneString(trackHub->name); clade->val = cloneString(trackHub->shortLabel); } return cladeList; } struct dbDb *trackHubGetDbDbs(char *clade) -/* get a list of dbDb structures for all the tracks in this clade/hub */ +/* Get a list of dbDb structures for all the tracks in this clade/hub. */ { struct dbDb *db, *dbList = NULL; if (globalAssemblyHubList != NULL) { struct trackHub *trackHub = globalAssemblyHubList; for(;trackHub; trackHub = trackHub->next) { if ((clade != NULL) && differentString(clade, trackHub->name)) continue; struct trackHubGenome *hubGenome = trackHub->genomeList; for(; hubGenome; hubGenome = hubGenome->next) { if (hubGenome->twoBitPath != NULL) { db = makeDbDbFromAssemblyGenome(hubGenome); slAddHead(&dbList, db); } } } } return dbList; } int trackHubChromCount(char *database) -/* return number of chromosomes in a assembly data hub */ +/* Return number of chromosomes in a assembly data hub. */ { struct hashEl *hel = hashLookup(hubAssemblyHash, database); if (hel == NULL) return 0; struct trackHubGenome *genome = hel->val; struct slName *chromList = twoBitSeqNamesExt(genome->twoBitPath, TRUE); return slCount(chromList); } struct slName *trackHubAllChromNames(char *database) -/* return a list of all the chrom names in this assembly hub database */ +/* Return a list of all the chrom names in this assembly hub database. */ { struct hashEl *hel = hashLookup(hubAssemblyHash, database); if (hel == NULL) return 0; struct trackHubGenome *genome = hel->val; struct slName *chromList = twoBitSeqNamesExt(genome->twoBitPath, TRUE); return chromList; } char *trackHubDefaultChrom(char *database) -/* return the default chromosome for this track hub assembly */ +/* Return the default chromosome for this track hub assembly. */ { struct hashEl *hel = hashLookup(hubAssemblyHash, database); if (hel == NULL) return NULL; struct trackHubGenome *genome = hel->val; struct slName *chromList = twoBitSeqNamesExt(genome->twoBitPath, TRUE); return chromList->name; } struct chromInfo *trackHubChromInfo(char *database, char *chrom) -/* return a chromInfo structure for just this chrom in this database */ +/* Return a chromInfo structure for just this chrom in this database. */ { if (hubAssemblyHash == NULL) return NULL; struct hashEl *hel = hashLookup(hubAssemblyHash, database); if (hel == NULL) return NULL; struct trackHubGenome *genome = hel->val; struct chromInfo *ci; AllocVar(ci); ci->chrom = cloneString(chrom); ci->fileName = genome->twoBitPath; ci->size = twoBitSeqSize(genome->tbf, chrom); return ci; } struct chromInfo *trackHubAllChromInfo(char *db) -/* return a chromInfo structure for all the chroms in this database */ +/* Return a chromInfo structure for all the chroms in this database. */ { struct hashEl *hel = hashLookup(hubAssemblyHash, db); if (hel == NULL) return NULL; struct trackHubGenome *genome = hel->val; struct chromInfo *ci, *ciList = NULL; struct slName *chromList = twoBitSeqNamesExt(genome->twoBitPath, TRUE); for(; chromList; chromList = chromList->next) { AllocVar(ci); ci->chrom = cloneString(chromList->name); ci->fileName = genome->twoBitPath; ci->size = twoBitSeqSize(genome->tbf, chromList->name); slAddHead(&ciList, ci); } return ciList; } static char *getRequiredGrpSetting(struct hash *hash, char *name, struct lineFile *lf) -/* grab a group setting out of the group hash. errAbort if not found */ +/* Grab a group setting out of the group hash. errAbort if not found. */ { char *str; if ((str = hashFindVal(hash, name)) == NULL) errAbort("missing required setting '%s' for group on line %d in file %s\n", name, lf->lineIx, lf->fileName); return str; } static struct grp *readGroupRa(char *groupFileName) -/* read in the ra file that describes the groups in an assembly hub */ +/* Read in the ra file that describes the groups in an assembly hub. */ { if (groupFileName == NULL) return NULL; struct hash *ra; struct grp *list = NULL; struct lineFile *lf = udcWrapShortLineFile(groupFileName, NULL, 16*1024*1024); while ((ra = raNextRecord(lf)) != NULL) { struct grp *grp; AllocVar(grp); slAddHead(&list, grp); grp->name = cloneString(getRequiredGrpSetting(ra, "name", lf)); grp->label = cloneString(getRequiredGrpSetting(ra, "label", lf)); grp->priority = atof(getRequiredGrpSetting(ra, "priority", lf)); grp->defaultIsClosed = sqlUnsigned(getRequiredGrpSetting(ra,"defaultIsClosed",lf)); hashFree(&ra); } if (list) slReverse(&list); lineFileClose(&lf); return list; } struct grp *trackHubLoadGroups(char *database) -/* load the grp structures for this track hub database */ +/* Load the grp structures for this track hub database. */ { if (hubAssemblyHash == NULL) return NULL; struct hashEl *hel = hashLookup(hubAssemblyHash, database); if (hel == NULL) return NULL; struct trackHubGenome *genome = hel->val; struct grp *list = readGroupRa(genome->groups); return list; } char *trackHubGenomeNameToDb(char *genome) -/* return assembly name given a genome name if one exists, otherwise NULL */ +/* Return assembly name given a genome name if one exists, otherwise NULL. */ { struct hashEl *hel; if ((hubOrgHash != NULL) && (hel = hashLookup(hubOrgHash, genome)) != NULL) { struct trackHub *hub = hel->val; struct trackHubGenome *genomeList = hub->genomeList; for(; genomeList; genomeList=genomeList->next) if ((genomeList->organism != NULL ) && sameString(genomeList->organism, genome)) return genomeList->name; } return NULL; } char *trackHubAssemblyClade(char *genome) -/* return the clade/hub_name that contains this genome */ +/* Return the clade/hub_name that contains this genome. */ { struct hashEl *hel; if ((hubOrgHash != NULL) && (hel = hashLookup(hubOrgHash, genome)) != NULL) { struct trackHub *hub = hel->val; return cloneString(hub->name); } return NULL; } static void addAssembly(char *name, struct trackHubGenome *genome, struct trackHub *hub) +/* Add a new assembly hub database to our global list. */ { struct hashEl *hel; if (hubCladeHash == NULL) hubCladeHash = newHash(5); if ((hel = hashLookup(hubCladeHash, hub->name)) == NULL) { hashAdd(hubCladeHash, hub->name, hub); slAddHead(&globalAssemblyHubList, hub); } if (hubOrgHash == NULL) hubOrgHash = newHash(5); if ((hel = hashLookup(hubOrgHash, genome->organism)) == NULL) @@ -558,30 +560,31 @@ char *oldVal = hel->val; hel->val = trackHubRelativeUrl(genome->trackDbFile, oldVal); freeMem(oldVal); } } struct trackHubGenome *trackHubFindGenome(struct trackHub *hub, char *genomeName) /* Return trackHubGenome of given name associated with hub. Return NULL if no * such genome. */ { return hashFindVal(hub->genomeHash, genomeName); } static void validateOneTrack( struct trackHub *hub, struct trackHubGenome *genome, struct trackDb *tdb) +/* Validate a track's trackDb entry. */ { /* Check for existence of fields required in all tracks */ requiredSetting(hub, genome, tdb, "shortLabel"); requiredSetting(hub, genome, tdb, "longLabel"); // subtracks is not NULL if a track said we were its parent if (tdb->subtracks != NULL) { boolean isSuper = FALSE; char *superTrack = trackDbSetting(tdb, "superTrack"); if ((superTrack != NULL) && startsWith("on", superTrack)) isSuper = TRUE; if (!(trackDbSetting(tdb, "compositeTrack") || trackDbSetting(tdb, "container") || @@ -598,31 +601,31 @@ if (!(startsWithWord("bigWig", type) || startsWithWord("bigBed", type) || startsWithWord("vcfTabix", type) || startsWithWord("bam", type))) { errAbort("Unsupported type '%s' in hub %s genome %s track %s", type, hub->url, genome->name, tdb->track); } requiredSetting(hub, genome, tdb, "bigDataUrl"); } } static void markContainers( struct trackHub *hub, struct trackHubGenome *genome, struct trackDb *tdbList) -/* mark containers that are parents, or have them */ +/* Mark containers that are parents, or have them. */ { struct hash *hash = hashNew(0); struct trackDb *tdb; // add all the track names to a hash for (tdb = tdbList; tdb != NULL; tdb = tdb->next) hashAdd(hash, tdb->track, tdb); // go through and find the container tracks for (tdb = tdbList; tdb != NULL; tdb = tdb->next) { char *parentLine = trackDbLocalSetting(tdb, "parent"); // maybe it's a child of a supertrack? if (parentLine == NULL) @@ -643,31 +646,31 @@ parent->subtracks = tdb; // ugh...do this so requiredSetting looks at parent // in the case of views. We clear this after // validating anyway tdb->parent = parent; freeMem(parentName); } } hashFree(&hash); } static void validateTracks( struct trackHub *hub, struct trackHubGenome *genome, struct trackDb *tdbList) -/* make sure a hub track list has the right settings and its parents exist */ +/* Make sure a hub track list has the right settings and its parents exist. */ { // mark the containers by setting their subtracks pointer markContainers(hub, genome, tdbList); /* Loop through list checking tags */ struct trackDb *tdb; for (tdb = tdbList; tdb != NULL; tdb = tdb->next) { validateOneTrack(hub, genome, tdb); // clear these two pointers which we set in markContainers tdb->subtracks = NULL; tdb->parent = NULL; } } @@ -728,31 +731,31 @@ reprefixString(&tdb->track, prefix); if (tdb->table != NULL) reprefixString(&tdb->table, prefix); } } void trackHubAddNamePrefix(char *hubName, struct trackDb *tdbList) /* For a hub named "hub_1" add the prefix "hub_1_" to each track and parent field. */ { char namePrefix[PATH_LEN]; safef(namePrefix, sizeof(namePrefix), "%s_", hubName); trackDbListAddNamePrefix(tdbList, namePrefix); } char *trackHubSkipHubName(char *name) -/* skip the hub_#_ prefix in a hub name */ +/* Skip the hub_#_ prefix in a hub name. */ { if ((name == NULL) || !startsWith("hub_", name)) return name; return strchr(&name[4], '_') + 1; } void trackHubAddGroupName(char *hubName, struct trackDb *tdbList) /* Add group tag that references the hubs symbolic name. */ { struct trackDb *tdb; for (tdb = tdbList; tdb != NULL; tdb = tdb->next) { tdb->grp = cloneString(hubName); hashReplace(tdb->settingsHash, "group", tdb->grp); } @@ -796,76 +799,76 @@ freez(&bigDataUrl); } errCatchEnd(errCatch); if (errCatch->gotError) { retVal = 1; dyStringPrintf(errors, "%s", errCatch->message->string); } errCatchFree(&errCatch); } return retVal; } void trackHubFixName(char *name) -/* change all characters other than alphanumeric, dash, and underbar - * to underbar */ +/* Change all characters other than alphanumeric, dash, and underbar + * to underbar. */ { if (name == NULL) return; char *in = name; char c; for(; (c = *in) != 0; in++) { if (c == ' ') break; if (!(isalnum(c) || c == '-' || c == '_')) *in = '_'; } } static void polishOneTrack( struct trackHub *hub, struct trackDb *bt, struct hash *hash) -/* get rid of special characters in track name, squirrel away a copy +/* Get rid of special characters in track name, squirrel away a copy * of the original name for html retrieval, make sure there aren't - * two tracks with the same name */ + * two tracks with the same name. */ { char *polished = trackDbSetting(bt, "polished"); if (polished != NULL) return; trackDbAddSetting(bt, "polished", "polished"); char *htmlName = trackDbSetting(bt, "html"); /* if the user didn't specify an html variable, set it to be the original * track name */ if (htmlName == NULL) trackDbAddSetting(bt, "html", bt->track); trackHubFixName(bt->track); if (hashLookup(hash, bt->track) != NULL) errAbort("more than one track called %s in hub %s\n", bt->track, hub->url); hashStore(hash, bt->track); } void trackHubPolishTrackNames(struct trackHub *hub, struct trackDb *tdbList) -/* remove all the special characters from trackHub track names */ +/* Remove all the special characters from trackHub track names. */ { struct trackDb *next, *tdb; struct hash *nameHash = hashNew(5); for (tdb = tdbList; tdb != NULL; tdb = next) { if (tdb->parent != NULL) polishOneTrack(hub, tdb->parent, nameHash); next = tdb->next; polishOneTrack(hub, tdb, nameHash); if (tdb->subtracks != NULL) { trackHubPolishTrackNames(hub, tdb->subtracks); } }